190 lines
7.0 KiB
Markdown
190 lines
7.0 KiB
Markdown
# 宝塔面板部署后台
|
|
|
|
推荐架构：`桌面端 → HTTPS 域名 → 宝塔 Nginx → 127.0.0.1:8765 → 后台容器`。
|
|
|
|
后台端口只监听服务器本机，不在云服务器安全组或宝塔防火墙中开放 `8765`。公网只开放 `80` 和 `443`。
|
|
|
|
## 一、准备域名
|
|
|
|
准备一个单独的二级域名，例如：
|
|
|
|
```text
|
|
ai-admin.example.com
|
|
```
|
|
|
|
在域名服务商处添加 A 记录，指向宝塔服务器的公网 IP。等待解析生效后再申请 SSL 证书。
|
|
|
|
## 二、上传后台文件
|
|
|
|
在宝塔“文件”中创建目录：
|
|
|
|
```text
|
|
/www/wwwroot/wechat-backend
|
|
```
|
|
|
|
推荐直接上传本项目生成的 `backend_deploy/wechat-backend-baota.zip`，并解压到上述目录。需要重新生成部署包时，在项目目录运行：
|
|
|
|
```powershell
|
|
powershell -ExecutionPolicy Bypass -File backend_deploy/build_baota_bundle.ps1
|
|
```
|
|
|
|
解压后应是以下结构，不需要上传桌面端的其他 Python 文件：
|
|
|
|
```text
|
|
/www/wwwroot/wechat-backend/
|
|
├── admin_backend.py
|
|
├── Dockerfile
|
|
├── compose.yaml
|
|
├── .env.example
|
|
└── README.md
|
|
```
|
|
|
|
在宝塔“文件”中把 `.env.example` 复制为 `.env`，再修改为：
|
|
|
|
```dotenv
|
|
WECOM_ADMIN_INITIAL_PASSWORD=替换成至少10位且包含字母和数字的强密码
|
|
BACKEND_PORT=8765
|
|
```
|
|
|
|
不要上传本机的 `backend_runtime.json`、`backend_connection.json` 或旧的 `.env`。
|
|
|
|
## 三、使用宝塔“Python 项目”启动
|
|
|
|
如果已经进入“添加 Python 项目”窗口，按下面填写：
|
|
|
|
| 字段 | 填写内容 |
|
|
| --- | --- |
|
|
| 项目名称 | `xchat` |
|
|
| Python 环境 | Python `3.10`、`3.11` 或 `3.12`，推荐 `3.12`；不能使用截图中的 `3.6.8` |
|
|
| 启动方式 | `命令行启动` |
|
|
| 项目路径 | `/www/wwwroot/xchat`，以实际上传目录为准 |
|
|
| 启动命令 | `python admin_backend.py --host 127.0.0.1 --port 8765 --db /www/wwwroot/xchat/backend.db --runtime-file /tmp/xchat_backend_runtime.json` |
|
|
| 环境变量 | 选择“指定变量”，添加 `WECOM_ADMIN_INITIAL_PASSWORD=你的强密码` |
|
|
| 启动用户 | `www` |
|
|
| 安装依赖包 | 留空，后台没有第三方依赖 |
|
|
|
|
如果项目实际解压在 `/www/wwwroot/wechat-backend`，启动命令中的 `/www/wwwroot/xchat` 也要改成 `/www/wwwroot/wechat-backend`。
|
|
|
|
确认项目目录允许 `www` 用户写入，否则后台无法创建 `backend.db`。在宝塔“文件”中把目录所有者设为 `www` 即可。
|
|
|
|
提交后打开项目日志。正常日志应包含：
|
|
|
|
```text
|
|
配置后台已启动：http://127.0.0.1:8765
|
|
```
|
|
|
|
然后在宝塔终端验证：
|
|
|
|
```bash
|
|
curl http://127.0.0.1:8765/health
|
|
```
|
|
|
|
如果返回包含 `"status": "ok"` 的 JSON，说明 Python 项目已经启动成功，可以直接跳到“创建网站和 SSL”。
|
|
|
|
## 四、使用 Docker 启动（备选）
|
|
|
|
在宝塔“Docker”中安装 Docker；也可以直接在宝塔“终端”执行下面的命令：
|
|
|
|
```bash
|
|
cd /www/wwwroot/wechat-backend
|
|
docker compose --env-file .env up -d --build
|
|
```
|
|
|
|
检查容器状态：
|
|
|
|
```bash
|
|
docker compose --env-file .env ps
|
|
curl http://127.0.0.1:8765/health
|
|
```
|
|
|
|
健康检查应返回包含 `"status": "ok"` 的 JSON。若构建失败，在宝塔“Docker → 容器编排”或终端中查看日志：
|
|
|
|
```bash
|
|
docker compose --env-file .env logs --tail=100 backend
|
|
```
|
|
|
|
## 五、在宝塔创建网站和 SSL
|
|
|
|
1. 进入“网站”，添加一个纯静态站点，域名填写准备好的二级域名。
|
|
2. 打开该站点的“SSL”，申请 Let's Encrypt 或 LiteSSL 证书。
|
|
3. 确认证书正常后开启“强制 HTTPS”。
|
|
4. 云服务器安全组和宝塔防火墙只需放行 `80`、`443`，不要放行 `8765`。
|
|
|
|
建议先申请证书，再配置反向代理，避免 HTTP 文件验证被代理规则影响。
|
|
|
|
## 六、配置反向代理
|
|
|
|
打开站点设置中的“反向代理”，新增一条规则：
|
|
|
|
| 宝塔字段 | 填写内容 |
|
|
| --- | --- |
|
|
| 代理名称 | `wechat-backend` |
|
|
| 目标 URL | `http://127.0.0.1:8765` |
|
|
| 发送域名 | `$host`，没有该选项时保持默认 |
|
|
| 内容替换 | 留空 |
|
|
| 缓存 | 关闭 |
|
|
|
|
保存后访问：
|
|
|
|
```text
|
|
https://ai-admin.example.com/health
|
|
```
|
|
|
|
能够看到健康检查 JSON 后，再访问域名首页登录后台。
|
|
|
|
## 七、首次登录和桌面端连接
|
|
|
|
1. 后台网页用户名为 `admin`。
|
|
2. 密码是 Python 项目环境变量或 `.env` 中设置的 `WECOM_ADMIN_INITIAL_PASSWORD`。
|
|
3. 首次登录会要求立即修改密码。
|
|
4. 在后台发布模型配置。
|
|
5. 在“桌面端版本升级”中设置当前正式版本、升级包下载地址和更新说明。
|
|
6. 桌面端固定从云端域名获取配置，无需在本机填写后台地址。
|
|
|
|
版本号使用 `1.0.0` 这种格式。云端版本与桌面端版本不一致时，软件启动会提示升级：
|
|
|
|
- 未开启“强制升级”：用户可以立即升级，也可以稍后继续使用。
|
|
- 开启“强制升级”：用户只能前往下载或退出软件，不能进入主界面。
|
|
|
|
开启强制升级前必须先填写一个可正常打开的 `http://` 或 `https://` 下载地址。当前桌面端版本可在软件窗口标题中查看。
|
|
|
|
发布新的桌面安装包时，还要把项目 `app_version.py` 中的 `APP_VERSION` 改成新版本号再打包。例如新安装包是 `1.0.1`，云端“最新版本号”和安装包内的版本号都应填写 `1.0.1`。
|
|
|
|
## 八、更新和备份
|
|
|
|
更新后台前，在宝塔终端执行：
|
|
|
|
```bash
|
|
cd /www/wwwroot/wechat-backend
|
|
docker compose --env-file .env stop backend
|
|
mkdir -p /www/backup/wechat-backend
|
|
docker cp wechat-config-backend:/data/backend.db /www/backup/wechat-backend/backend.db
|
|
docker compose --env-file .env start backend
|
|
```
|
|
|
|
然后覆盖新的 `admin_backend.py` 并重新构建：
|
|
|
|
```bash
|
|
docker compose --env-file .env up -d --build
|
|
```
|
|
|
|
不要执行 `docker compose down -v`，它会删除保存数据库的数据卷。
|
|
|
|
## 九、常见问题
|
|
|
|
- 日志提示 `hashlib has no attribute pbkdf2_hmac`：旧部署包不兼容宝塔中缺少 OpenSSL PBKDF2 的 Python 环境。上传最新版 `admin_backend.py` 后重启项目。
|
|
- 域名返回 `502 Bad Gateway`：后台容器未启动，或 `127.0.0.1:8765` 健康检查失败。
|
|
- 证书申请失败：确认域名已经解析到服务器；暂时关闭反向代理后重新申请。
|
|
- 桌面端提示无法连接：必须填写完整的 `https://后台域名`，并确保证书受系统信任。
|
|
- 修改 `.env` 密码没有效果：初始密码只在第一次创建数据库时使用，后续密码请在后台网页中修改。
|
|
- 修改版本策略后桌面端没提示：确认桌面端程序已更新到包含版本检查的新版本，并重新完整退出、打开软件。
|
|
- 忘记管理员密码：先停止后台，再使用 Compose 临时任务运行密码重置命令，完成后重新启动：
|
|
|
|
```bash
|
|
docker compose --env-file .env stop backend
|
|
docker compose --env-file .env run --rm backend python /app/admin_backend.py --db /data/backend.db --reset-admin-password
|
|
docker compose --env-file .env start backend
|
|
```
|
|
|
|
通用部署方式见 [BACKEND_DEPLOY.md](BACKEND_DEPLOY.md)。
|