kefu/wechat_rpa/BACKEND_DEPLOY.md

后台独立部署

配置后台是一个独立的 HTTP 服务。桌面端不会自动把后台部署到服务器；必须先在一台长期在线的电脑或服务器上启动后台，再让各桌面端连接它。

使用宝塔面板时，请直接查看 BAOTA_DEPLOY.md，里面按宝塔的“文件、Docker、网站、SSL、反向代理”页面逐步说明。

需要部署哪些文件

最小部署只需要：

• admin_backend.py：后台程序，只有 Python 标准库依赖。
• ai_settings.json：可选，仅用于第一次创建数据库时导入初始模型配置。

以下文件不要从开发电脑复制到新服务器：

• backend_runtime.json：本机运行时自动生成，包含临时同步凭证。
• backend_connection.json：桌面端的登录状态，不属于后台。
• backend.db：新部署无需复制；迁移旧后台时才复制，并应妥善保管。

后台首次启动后会创建 backend.db。它保存账号、配置和审计记录，是需要定期备份的核心数据文件。

方案一：Docker 部署（推荐）

项目已经把 Docker 部署文件单独放在 backend_deploy 目录中。在项目根目录执行：

Copy-Item backend_deploy\.env.example backend_deploy\.env
notepad backend_deploy\.env
docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml up -d --build

编辑 .env 时至少设置一个不少于 10 位、同时包含字母和数字的初始管理员密码：

WECOM_ADMIN_INITIAL_PASSWORD=请替换为强密码
BACKEND_BIND_IP=127.0.0.1
BACKEND_PORT=8765

BACKEND_BIND_IP 的选择：

• 只允许服务器本机访问：保持 127.0.0.1。
• 需要局域网电脑直连：改为 0.0.0.0，并只对可信局域网放行端口。
• 需要公网访问：保持 127.0.0.1，通过 Nginx 或 Caddy 提供 HTTPS，禁止直接暴露 HTTP 端口。

检查运行状态：

docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml ps
Invoke-RestMethod http://127.0.0.1:8765/health

查看日志：

docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml logs -f backend

停止服务不会删除数据库：

docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml down

不要执行 down -v，它会删除保存后台数据库的 Docker 数据卷。

方案二：直接运行 Python

服务器安装 Python 3.10 或更高版本后，把 admin_backend.py 放到一个单独目录中，然后运行：

python admin_backend.py --host 0.0.0.0 --port 8765

该方式不需要安装 requirements.txt 中的桌面端依赖。正式使用时应把命令配置为 Windows 服务、计划任务或 Linux systemd 服务，确保服务器重启后自动启动。

首次启动默认账号为 admin。如果没有通过环境变量指定密码，默认初始密码为 Admin@123456；首次登录会强制修改。正式部署不要继续使用默认密码。

桌面端如何连接

1. 浏览器打开后台地址并完成管理员首次登录和密码修改。
2. 在后台发布模型与 MCP 配置。
3. 打开桌面端“AI 人格与能力”页面。
4. 在“后台同步”区域点击“登录后台”。
5. 后台地址填写服务器地址，例如 http://192.168.1.20:8765；使用反向代理时填写 https://你的域名。

登录后桌面端会立即同步，此后会在启动时和运行期间自动同步。

数据备份与升级

Docker 部署的数据保存在 wechat-backend-data 数据卷中。升级前先备份数据库，再重新构建服务：

docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml up -d --build

直接运行 Python 时，停止后台后复制 backend.db 即可完成一致性备份。恢复时把数据库放回原目录，再启动后台。

常见连接失败

• WinError 10061：目标地址没有服务监听。确认后台进程或容器已经启动，并核对 IP 与端口。
• 服务器本机能打开、其他电脑不能：确认监听地址为 0.0.0.0，并检查系统防火墙和云服务器安全组。
• 浏览器能打开、桌面端不能：登录框中的地址必须包含 http:// 或 https://，不要填写后台管理页的子路径。
• 公网域名连接失败：检查 HTTPS 证书与反向代理，不要在桌面端使用自签名证书。