7.0 KiB
宝塔面板部署后台
推荐架构：桌面端 → HTTPS 域名 → 宝塔 Nginx → 127.0.0.1:8765 → 后台容器。
后台端口只监听服务器本机，不在云服务器安全组或宝塔防火墙中开放 8765。公网只开放 80 和 443。
一、准备域名
准备一个单独的二级域名，例如：
ai-admin.example.com
在域名服务商处添加 A 记录，指向宝塔服务器的公网 IP。等待解析生效后再申请 SSL 证书。
二、上传后台文件
在宝塔“文件”中创建目录：
/www/wwwroot/wechat-backend
推荐直接上传本项目生成的 backend_deploy/wechat-backend-baota.zip，并解压到上述目录。需要重新生成部署包时，在项目目录运行：
powershell -ExecutionPolicy Bypass -File backend_deploy/build_baota_bundle.ps1
解压后应是以下结构，不需要上传桌面端的其他 Python 文件：
/www/wwwroot/wechat-backend/
├── admin_backend.py
├── Dockerfile
├── compose.yaml
├── .env.example
└── README.md
在宝塔“文件”中把 .env.example 复制为 .env，再修改为：
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 即可。
提交后打开项目日志。正常日志应包含：
配置后台已启动：http://127.0.0.1:8765
然后在宝塔终端验证：
curl http://127.0.0.1:8765/health
如果返回包含 "status": "ok" 的 JSON，说明 Python 项目已经启动成功，可以直接跳到“创建网站和 SSL”。
四、使用 Docker 启动（备选）
在宝塔“Docker”中安装 Docker；也可以直接在宝塔“终端”执行下面的命令：
cd /www/wwwroot/wechat-backend
docker compose --env-file .env up -d --build
检查容器状态：
docker compose --env-file .env ps
curl http://127.0.0.1:8765/health
健康检查应返回包含 "status": "ok" 的 JSON。若构建失败，在宝塔“Docker → 容器编排”或终端中查看日志：
docker compose --env-file .env logs --tail=100 backend
五、在宝塔创建网站和 SSL
- 进入“网站”，添加一个纯静态站点，域名填写准备好的二级域名。
- 打开该站点的“SSL”，申请 Let's Encrypt 或 LiteSSL 证书。
- 确认证书正常后开启“强制 HTTPS”。
- 云服务器安全组和宝塔防火墙只需放行
80、443，不要放行8765。
建议先申请证书，再配置反向代理，避免 HTTP 文件验证被代理规则影响。
六、配置反向代理
打开站点设置中的“反向代理”，新增一条规则：
| 宝塔字段 | 填写内容 |
|---|---|
| 代理名称 | wechat-backend |
| 目标 URL | http://127.0.0.1:8765 |
| 发送域名 | $host，没有该选项时保持默认 |
| 内容替换 | 留空 |
| 缓存 | 关闭 |
保存后访问：
https://ai-admin.example.com/health
能够看到健康检查 JSON 后，再访问域名首页登录后台。
七、首次登录和桌面端连接
- 后台网页用户名为
admin。 - 密码是 Python 项目环境变量或
.env中设置的WECOM_ADMIN_INITIAL_PASSWORD。 - 首次登录会要求立即修改密码。
- 在后台发布模型配置。
- 在“桌面端版本升级”中设置当前正式版本、升级包下载地址和更新说明。
- 桌面端固定从云端域名获取配置，无需在本机填写后台地址。
版本号使用 1.0.0 这种格式。云端版本与桌面端版本不一致时，软件启动会提示升级：
- 未开启“强制升级”：用户可以立即升级，也可以稍后继续使用。
- 开启“强制升级”：用户只能前往下载或退出软件，不能进入主界面。
开启强制升级前必须先填写一个可正常打开的 http:// 或 https:// 下载地址。当前桌面端版本可在软件窗口标题中查看。
发布新的桌面安装包时，还要把项目 app_version.py 中的 APP_VERSION 改成新版本号再打包。例如新安装包是 1.0.1，云端“最新版本号”和安装包内的版本号都应填写 1.0.1。
八、更新和备份
更新后台前，在宝塔终端执行：
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 并重新构建：
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 临时任务运行密码重置命令，完成后重新启动：
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。