# 部署文档

## 一、环境要求

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | CentOS 7+ / Ubuntu 20.04+ / Windows Server 2019+ | Ubuntu 22.04 LTS |
| Docker | 24.0+ | 最新稳定版 |
| Docker Compose | v2.20+（随 Docker 一起安装） | 最新稳定版 |
| CPU | 2 核 | 4 核+ |
| 内存 | 4 GB | 8 GB+（模型推理和向量化需要更多内存） |
| 磁盘 | 20 GB | 50 GB+（知识库文档和向量数据会持续增长） |
| 网络 | 能访问外部模型 API | 带宽 10Mbps+ |

**端口占用：**
- 80：Nginx（HTTP 访问入口）
- 5432：PostgreSQL（仅容器内部通信，可不对外暴露）
- 6379：Redis（仅容器内部通信，可不对外暴露）
- 8080：Django Web（仅容器内部通信，Nginx 反向代理）

---

## 二、部署步骤

### 第一步：安装 Docker

**Ubuntu / Debian：**
```bash
# 安装 Docker
curl -fsSL https://get.docker.com | sh

# 启动并设置开机自启
systemctl enable docker
systemctl start docker

# 验证安装
docker --version
docker compose version
```

**CentOS / RHEL：**
```bash
yum install -y yum-utils
yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable docker
systemctl start docker
```

**Windows Server：**
- 安装 Docker Desktop for Windows
- 或使用 WSL2 + Docker Engine

---

### 第二步：获取项目代码

```bash
# 克隆代码到服务器
git clone <仓库地址> /opt/zhagent
cd /opt/zhagent
```

如果服务器无法访问 Git 仓库，可以在开发机打包后上传：
```bash
# 开发机上打包
tar -czf zhagent.tar.gz --exclude='.venv' --exclude='node_modules' --exclude='.git' zhagent/

# 上传到服务器后解压
tar -xzf zhagent.tar.gz -C /opt/
cd /opt/zhagent
```

---

### 第三步：配置环境变量

```bash
cp .env.example .env
vim .env
```

**必须修改的配置：**

```ini
# ===== 平台名称 =====
APP_TITLE=四川路桥Maas智能体平台
APP_VERSION=v1.0

# ===== 数据库密码（务必修改为强密码）=====
DB_PASSWORD=YourStrongPassword123!

# ===== SSO 配置（如需单点登录）=====
SSO_BASE_URL=http://your-sso-server:8200
SSO_CLIENT_ID=your_client_id
SSO_CLIENT_SECRET=your_client_secret
SSO_REDIRECT_URI=http://your-platform-domain/admin/auth/callback
SSO_LOGOUT_REDIRECT_URL=http://your-sso-server/login

# ===== 样本中心（如需对接）=====
SAMPLE_CENTER_BASE_URL=http://sample-center-server:port
SAMPLE_CENTER_APP_ID=your_app_id
SAMPLE_CENTER_APP_SECRET=your_app_secret
```

**可选修改：**
```ini
# 关闭调试模式（生产环境必须关闭）
DEBUG=false

# 数据存储路径（默认在项目目录下的 data/）
DATA_PATH=./data
UPLOAD_PATH=./data/uploads
```

---

### 第四步：构建前端（自定义平台名称时需要）

如果需要修改浏览器标签页显示的标题，需要重新构建前端。如果使用默认名称可跳过此步。

```bash
# 需要 Node.js 18+ 环境
# 安装 Node.js（如服务器没有）
curl -fsSL https://deb.nodesource.com/setup_18.x | bash -
apt-get install -y nodejs

# 修改前端标题
sed -i 's/VITE_APP_TITLE=.*/VITE_APP_TITLE=四川路桥Maas智能体平台v1.0/' ui/env/.env.admin
sed -i 's/VITE_APP_TITLE=.*/VITE_APP_TITLE=四川路桥Maas智能体平台v1.0/' ui/env/.env.chat
sed -i 's/VITE_APP_TITLE=.*/VITE_APP_TITLE=四川路桥Maas智能体平台v1.0/' ui/env/.env.builder

# 安装依赖并构建
cd ui
npm install
npm run build-only-admin
npm run build-only-chat
npm run build-only-builder

# 复制构建产物
cp -r dist/admin/* ../apps/static/admin/
cp -r dist/chat/* ../apps/static/chat/
cp -r dist/builder/* ../apps/static/builder/
cd ..
```

> **提示：** 也可以在开发机构建好后，将 `apps/static/` 目录一起打包部署，服务器上就不需要 Node.js 环境。

---

### 第五步：一键启动

```bash
docker compose up -d
```

首次启动会自动：
1. 拉取基础镜像（python:3.11-slim、postgres:16、redis:7、nginx:alpine）
2. 构建后端应用镜像
3. 启动所有容器
4. 自动执行数据库迁移
5. 创建默认管理员账号

整个过程约 3-10 分钟（取决于网络速度和服务器性能）。

---

### 第六步：验证部署

```bash
# 1. 查看容器状态（全部 Up 即正常）
docker compose ps

# 预期输出：
# zhagent-db       Up (healthy)
# zhagent-redis    Up (healthy)
# zhagent-web      Up
# zhagent-celery   Up
# zhagent-nginx    Up

# 2. 等待后端完全启动（约 30-60 秒）
docker compose logs web --tail 5
# 看到 SQL 查询日志或 "Listening" 字样即启动完成

# 3. 测试 API
curl http://localhost/admin/api/profile
# 应返回 JSON：{"code":200,"data":{"app_title":"四川路桥Maas智能体平台",...}}
```

---

### 第七步：访问平台

浏览器打开：`http://<服务器IP>/admin/`

- **默认管理员账号：** admin
- **默认密码：** admin123
- **首次登录后请立即修改密码**

---

## 三、服务说明

| 容器名 | 服务 | 作用 |
|--------|------|------|
| zhagent-nginx | Nginx | HTTP 入口，反向代理 API 请求，托管前端静态文件 |
| zhagent-web | Django | 后端 API 服务，处理所有业务逻辑 |
| zhagent-celery | Celery Worker | 异步任务执行（文档向量化、定时触发器、数据同步等） |
| zhagent-db | PostgreSQL + pgvector | 关系数据存储 + 向量检索 |
| zhagent-redis | Redis | 缓存 + 消息队列（Celery Broker） |

---

## 四、数据持久化

所有数据存储在宿主机目录，容器删除后数据不会丢失：

| 数据类型 | 宿主机路径 | 说明 |
|----------|-----------|------|
| 数据库文件 | `${DATA_PATH}/postgresql/` | PostgreSQL 数据文件 |
| Redis 数据 | `${DATA_PATH}/redis/` | Redis 持久化文件 |
| 上传文件 | `${UPLOAD_PATH}/` | 用户上传的文档、图片等 |

默认 `DATA_PATH=./data`，即项目目录下的 `data/` 文件夹。

---

## 五、日常运维

### 查看日志
```bash
# 后端日志
docker compose logs -f web

# 异步任务日志
docker compose logs -f celery

# 所有服务日志
docker compose logs -f

# 只看最近 100 行
docker compose logs --tail 100 web
```

### 重启服务
```bash
# 重启后端（修改代码或配置后）
docker compose restart web celery

# 重启所有服务
docker compose restart

# 完全停止所有服务
docker compose down

# 停止并删除数据卷（⚠️ 会丢失所有数据）
docker compose down -v
```

### 重新构建
```bash
# 代码更新后重新构建镜像并启动
docker compose up -d --build

# 只重新构建后端
docker compose build web celery
docker compose up -d --force-recreate web celery
```

### 进入容器调试
```bash
# 进入后端容器
docker exec -it zhagent-web bash

# 进入数据库
docker exec -it zhagent-db psql -U postgres -d maxkb

# 执行 Django 管理命令
docker exec -it zhagent-web python manage.py shell
```

### 数据库备份与恢复
```bash
# 备份
docker exec zhagent-db pg_dump -U postgres maxkb > backup_$(date +%Y%m%d_%H%M%S).sql

# 恢复
cat backup_20260522.sql | docker exec -i zhagent-db psql -U postgres maxkb

# 建议设置定时备份（crontab）
# 每天凌晨 2 点自动备份
0 2 * * * cd /opt/zhagent && docker exec zhagent-db pg_dump -U postgres maxkb > backups/backup_$(date +\%Y\%m\%d).sql
```

---

## 六、升级流程

```bash
cd /opt/zhagent

# 1. 备份数据库（重要！）
docker exec zhagent-db pg_dump -U postgres maxkb > backup_before_upgrade_$(date +%Y%m%d).sql

# 2. 拉取最新代码
git pull origin master

# 3. 如有前端变更，重新构建前端
cd ui && npm install && npm run build-only-admin
cp -r dist/admin/* ../apps/static/admin/
cd ..

# 4. 重新构建镜像并重启
docker compose up -d --build

# 5. 等待启动完成后验证
sleep 30
curl http://localhost/admin/api/profile
```

---

## 七、HTTPS 配置（生产环境推荐）

### 方式一：使用 Let's Encrypt 免费证书

```bash
# 安装 certbot
apt install -y certbot

# 获取证书（需要域名已解析到服务器）
certbot certonly --standalone -d your-domain.com

# 修改 nginx.conf 添加 SSL 配置
```

### 方式二：使用已有证书

将证书文件放到服务器上，修改 `nginx.conf`：

```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    # ... 其余配置不变
}

server {
    listen 80;
    return 301 https://$host$request_uri;
}
```

修改 `docker-compose.yml` 中 nginx 的端口映射和证书挂载。

---

## 八、常见问题排查

| 现象 | 可能原因 | 解决方法 |
|------|----------|----------|
| 访问返回 502 Bad Gateway | 后端还在启动中（初始化约 30-60 秒） | 等待后重试，或 `docker compose logs web` 查看进度 |
| 登录页面空白 | 前端静态文件缺失 | 确认 `apps/static/admin/index.html` 存在，重新构建前端 |
| 登录提示密码错误 | 密码不正确 | 进入数据库重置：`UPDATE "user" SET password=md5('新密码') WHERE username='admin'` |
| SSO 登录回调报错 | 回调地址配置不匹配 | 检查 `.env` 中 `SSO_REDIRECT_URI` 与 SSO 平台配置一致 |
| 知识库向量化一直"处理中" | Celery Worker 异常 | `docker compose logs celery` 查看错误，`docker compose restart celery` |
| 容器启动后立即退出 | 端口被占用或配置错误 | `docker compose logs <容器名>` 查看具体错误 |
| 数据库连接失败 | 密码不匹配或数据库未就绪 | 确认 `.env` 中密码正确，等待 db 容器 healthy |
| 上传文件失败 | 磁盘空间不足或权限问题 | `df -h` 检查磁盘，确认 uploads 目录可写 |
| 模型调用失败 | API Key 无效或网络不通 | 检查模型配置的 API Key，确认服务器能访问模型 API |

---

## 九、安全加固建议

1. **修改默认密码**：部署后立即修改 admin 密码和数据库密码
2. **关闭调试模式**：`.env` 中设置 `DEBUG=false`
3. **配置 HTTPS**：生产环境必须使用 HTTPS
4. **限制端口暴露**：`docker-compose.yml` 中去掉 db 和 redis 的 ports 映射（仅内部通信）
5. **防火墙配置**：只开放 80/443 端口
6. **定期备份**：设置 crontab 每日自动备份数据库
7. **日志监控**：关注 ERROR 级别日志，建议接入日志收集系统
8. **更新维护**：定期更新依赖包，修复安全漏洞