部署文档

一、环境要求

项目	最低要求	推荐配置
操作系统	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：

# 安装 Docker
curl -fsSL https://get.docker.com | sh

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

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

CentOS / RHEL：

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

第二步：获取项目代码

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

如果服务器无法访问 Git 仓库，可以在开发机打包后上传：

# 开发机上打包
tar -czf zhagent.tar.gz --exclude='.venv' --exclude='node_modules' --exclude='.git' zhagent/

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

第三步：配置环境变量

cp .env.example .env
vim .env

必须修改的配置：

# ===== 平台名称 =====
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

可选修改：

# 关闭调试模式（生产环境必须关闭）
DEBUG=false

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

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

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

# 需要 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 环境。

第五步：一键启动

docker compose up -d

首次启动会自动：

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

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

第六步：验证部署

# 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/ 文件夹。

五、日常运维

查看日志

# 后端日志
docker compose logs -f web

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

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

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

重启服务

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

# 重启所有服务
docker compose restart

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

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

重新构建

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

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

进入容器调试

# 进入后端容器
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

数据库备份与恢复

# 备份
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

六、升级流程

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 免费证书

# 安装 certbot
apt install -y certbot

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

# 修改 nginx.conf 添加 SSL 配置

方式二：使用已有证书

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

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

九、安全加固建议

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

部署文档.md 10 KB Permalink History Raw