Inicio Explorar Ayuda
Registro Iniciar sesión
Maas2-group
/
Maas-Agent
5
0
Fork 0
Archivos Incidencias 0 Pull Requests 0 Wiki
Árbol: 4b604c85bc
Ramas Etiquetas
Maas-Agent
/
部署文档.md

部署文档.md 10 KB
Histórico Raw

部署文档

一、环境要求

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

首次启动会自动：

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

整个过程约 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

九、安全加固建议

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