105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# 后台独立部署
|
|
|
|
配置后台是一个独立的 HTTP 服务。桌面端不会自动把后台部署到服务器；必须先在一台长期在线的电脑或服务器上启动后台，再让各桌面端连接它。
|
|
|
|
使用宝塔面板时，请直接查看 [BAOTA_DEPLOY.md](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` 目录中。在项目根目录执行：
|
|
|
|
```powershell
|
|
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 位、同时包含字母和数字的初始管理员密码：
|
|
|
|
```dotenv
|
|
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 端口。
|
|
|
|
检查运行状态：
|
|
|
|
```powershell
|
|
docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml ps
|
|
Invoke-RestMethod http://127.0.0.1:8765/health
|
|
```
|
|
|
|
查看日志：
|
|
|
|
```powershell
|
|
docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml logs -f backend
|
|
```
|
|
|
|
停止服务不会删除数据库：
|
|
|
|
```powershell
|
|
docker compose --env-file backend_deploy/.env -f backend_deploy/compose.yaml down
|
|
```
|
|
|
|
不要执行 `down -v`，它会删除保存后台数据库的 Docker 数据卷。
|
|
|
|
## 方案二：直接运行 Python
|
|
|
|
服务器安装 Python 3.10 或更高版本后，把 `admin_backend.py` 放到一个单独目录中，然后运行：
|
|
|
|
```powershell
|
|
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` 数据卷中。升级前先备份数据库，再重新构建服务：
|
|
|
|
```powershell
|
|
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 证书与反向代理，不要在桌面端使用自签名证书。
|