# 后台独立部署

配置后台是一个独立的 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 证书与反向代理，不要在桌面端使用自签名证书。