aiagent/docs/腾讯云Linux部署指南.md

天工智能体平台 — 腾讯云 Linux 部署指南

一、项目架构概览

组件	技术栈	端口	说明
前端	React (Nginx)	8038	Web 管理界面
后端	FastAPI (Python 3.11)	8037	REST API + Agent 运行时
数据库	MySQL 8.0	3306	持久化存储
缓存	Redis 7	6379	会话缓存 + Celery 消息队列
异步任务	Celery Worker	-	后台任务执行
定时调度	Celery Beat	-	定时任务触发
监控	Prometheus	9090	指标采集
可视化	Grafana	3000	监控面板
日志	Elasticsearch + Kibana + Filebeat	9200 / 5601	日志聚合分析

所有服务通过 Docker Compose 编排，统一在 aiagent-net 桥接网络中通信。

重要：本项目在 101.43.95.130 的实际生产部署与本指南默认假设有三处差异，升级/运维前务必先看：

1. 数据库是外部腾讯云 CloudDB（TDSQL-C），不是容器 MySQL。 docker-compose.prod.yml 里没有 mysql 服务，也就没有 aiagent-mysql 容器。凡是 docker exec aiagent-mysql ... 的命令都要改成直连外部实例（见第六、七、九节的「外部数据库」写法）。
2. 服务器在国内，docker compose build 常卡在 apt-get / PyPI（files.pythonhosted.org）超时。 构建或装包需走国内镜像源（见第四节）。
3. 升级不要盲目 alembic upgrade。 公司模块迁移 d684c9b30c1c 是 autogenerate 的破坏性迁移（会 drop 掉 tools/api_keys 等已有数据的表），且线上库对应表已存在。正确做法见第六节「增量升级」。

实际部署目录为 /home/renjianbo/aiagent（本指南示例用 /opt/aiagent，按需替换）。

---

二、服务器要求

最低配置

资源	要求
操作系统	CentOS 7+ / Ubuntu 20.04+ / Debian 11+
CPU	4 核
内存	8 GB（ELK 栈占用较高）
磁盘	50 GB 可用空间
网络	公网 IP（已开放 8037/8038 端口）

腾讯云推荐机型

• 轻量应用服务器：4核8G，系统镜像选 Ubuntu 22.04 或 CentOS 7.9
• CVM 云服务器：S5.MEDIUM4 及以上

防火墙/安全组配置

在腾讯云控制台「安全组」中放行以下入站端口：

端口	用途	建议
22	SSH 远程管理	仅允许你的 IP
8037	后端 API	可限定前端 IP 或按需开放
8038	前端页面	公网访问
9090	Prometheus	仅内网或不开放
3000	Grafana	按需开放
5601	Kibana	仅内网或不开放

---

三、环境准备

1. 安装 Docker

# Ubuntu / Debian
curl -fsSL https://get.docker.com | bash
sudo usermod -aG docker $USER
# 退出重新登录使权限生效

# CentOS 7
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable docker --now
sudo usermod -aG docker $USER

验证安装：

docker --version          # >= 24.0
docker compose version    # >= v2.20

2. 安装 Git

# Ubuntu / Debian
sudo apt install -y git

# CentOS
sudo yum install -y git

3. 系统调优（可选但推荐）

# 提高虚拟内存上限（Elasticsearch 需要）
sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee -a /etc/sysctl.conf

---

四、部署步骤

1. 克隆项目

cd /opt
git clone <你的仓库地址> aiagent
cd aiagent

2. 配置环境变量

运行一键安装脚本（交互式配置）：

bash install.sh

脚本会引导你填写以下信息：

配置项	说明	示例
MySQL root 密码	数据库 root 密码	你的强密码
JWT 密钥	自动生成即可	回车自动生成
DeepSeek API Key	AI 模型 API Key（必填）	sk-xxxx
OpenAI API Key	可选	sk-xxxx
外部访问地址	服务器的公网地址	http://你的IP

或者手动创建 backend/.env：

APP_NAME=天工智能体平台
APP_VERSION=1.0.0
DEBUG=False
SECRET_KEY=<随机生成的密钥>

# 数据库 — 使用容器内地址
DATABASE_URL=mysql+pymysql://root:<你的密码>@mysql:3306/agent_db?charset=utf8mb4

# 如果使用腾讯云数据库（TDSQL-C），改为：
# DATABASE_URL=mysql+pymysql://root:<密码>@gz-cynosdbmysql-grp-xxx.sql.tencentcdb.com:24936/agent_db?charset=utf8mb4

# Redis
REDIS_URL=redis://redis:6379/0

# JWT
JWT_SECRET_KEY=<随机生成的密钥>
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS（多个地址逗号分隔）
CORS_ORIGINS=http://localhost:8038,http://<你的服务器IP>:8038

# AI API Keys
DEEPSEEK_API_KEY=sk-xxxx
OPENAI_API_KEY=sk-xxxx

# 外部访问地址
EXTERNAL_URL=http://<你的服务器IP>

# 其他
HSTS_ENABLED=True
WORKFLOW_MAX_STEPS_PER_RUN=2000
WORKFLOW_MAX_LLM_INVOCATIONS_PER_RUN=200
WORKFLOW_MAX_TOOL_CALLS_PER_RUN=500
MEMORY_PERSIST_DB_ENABLED=True

3. 构建并启动

# 构建镜像（含拉取基础镜像）
docker compose -f docker-compose.prod.yml build --pull

# 启动所有服务（后台运行）
docker compose -f docker-compose.prod.yml up -d

国内服务器注意（重要）：在腾讯云等国内服务器上，docker compose build 经常卡在 apt-get update 或 files.pythonhosted.org 超时。处理办法：

• 给 Docker 配镜像加速（构建时拉基础镜像）：编辑 /etc/docker/daemon.json 加入

  { "registry-mirrors": ["https://mirror.ccs.tencentyun.com"] }
  

  然后 sudo systemctl restart docker（mirror.ccs.tencentyun.com 为腾讯云内网加速地址）。
• 给 pip 换国内源：在 backend/Dockerfile 的 pip 安装步骤加 -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com。
• 临时给已运行容器补一个 Python 包（不想重建镜像时）：

  docker exec <容器名> pip install -i https://mirrors.aliyun.com/pypi/simple/ \
    --trusted-host mirrors.aliyun.com <包名>==<版本>
  

4. 验证部署

# 查看服务状态
docker compose -f docker-compose.prod.yml ps

# 检查后端健康
curl -s http://localhost:8037/docs

# 检查前端
curl -s http://localhost:8038 | head -20

# 查看后端日志
docker compose -f docker-compose.prod.yml logs -f backend

服务正常启动后，预期看到约 10 个容器全部 Up 状态：

NAME                    STATUS
aiagent-mysql           Up (healthy)
aiagent-redis           Up (healthy)
aiagent-backend         Up
aiagent-celery-worker   Up
aiagent-celery-beat     Up
aiagent-frontend        Up
aiagent-prometheus      Up
aiagent-grafana         Up
aiagent-elasticsearch   Up (healthy)
aiagent-kibana          Up
aiagent-filebeat        Up

使用外部腾讯云数据库时：没有 aiagent-mysql 容器（少一个）。核心服务确认 aiagent-backend、aiagent-redis、aiagent-frontend、两个 celery 均为 Up，且 curl -s -o /dev/null -w '%{http_code}' http://localhost:8037/docs 返回 200 即为正常。

---

五、访问地址

服务	URL	默认账号
前端管理界面	http://<服务器IP>:8038	admin / 123456
后端 API 文档	http://<服务器IP>:8037/docs	-
Grafana 监控	http://<服务器IP>:3000	admin / admin123
Prometheus	http://<服务器IP>:9090	-
Kibana 日志	http://<服务器IP>:5601	-

---

六、日常运维

查看日志

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

# 只看后端日志（最近 200 行）
docker compose -f docker-compose.prod.yml logs --tail 200 backend

# 只看 MySQL
docker compose -f docker-compose.prod.yml logs mysql

重启服务

# 重启后端
docker compose -f docker-compose.prod.yml restart backend

# 重启前端（Nginx 热重载也可）
docker compose -f docker-compose.prod.yml restart frontend

# 重启全部
docker compose -f docker-compose.prod.yml restart

停止/启动

# 停止所有服务（数据卷保留）
docker compose -f docker-compose.prod.yml down

# 重新启动
docker compose -f docker-compose.prod.yml up -d

增量升级

升级前必读（本项目实测坑）：

1. 构建可能失败：docker compose build --pull 在国内服务器常因 apt/PyPI 超时卡死，先按第四节配好国内镜像；急用时可用「docker cp 热更新 + 补依赖」绕过（见下方备用步骤 2B/3）。
2. 迁移要小心：公司模块迁移 d684c9b30c1c_add_company_tables 是破坏性的（会 drop_table tools/api_keys/fcm_tokens 等）。若线上库里 companies/company_projects 等表已存在，不要执行 alembic upgrade，而是标记版本：

   docker exec aiagent-backend sh -c "cd /app && alembic stamp d684c9b30c1c"
   

3. 新依赖：新代码引入了 APScheduler==3.10.4（公司调度用）。旧镜像若没有，backend 会 ModuleNotFoundError: No module named 'apscheduler' 崩溃，需按第四节临时装包（backend + 两个 celery 都要装）。

项目提供了 upgrade.sh 脚本实现零停机升级：

bash upgrade.sh

脚本执行流程：

1. 备份当前 .env 配置到 backups/ 目录
2. 备份 MySQL 数据库（如容器在运行）
3. 拉取最新基础镜像并重新构建
4. 按依赖顺序滚动重启（mysql/redis → backend/celery → frontend）
5. 清理旧镜像，释放磁盘空间
6. 验证后端健康状态

手动升级步骤（国内服务器 / 外部数据库实测流程）：

cd /home/renjianbo/aiagent   # 或 /opt/aiagent

# 1. 拉取最新代码
git pull

# 2A. 常规：重建镜像并重启（网络好、已配国内镜像时）
docker compose -f docker-compose.prod.yml build --pull
docker compose -f docker-compose.prod.yml up -d

# 2B. 备用：build 卡死时，热更新已运行容器的代码（不重建镜像）
docker cp backend/app     aiagent-backend:/app/
docker cp backend/alembic aiagent-backend:/app/
docker cp backend/app     aiagent-celery-worker:/app/
docker cp backend/app     aiagent-celery-beat:/app/

# 3. 有新 Python 依赖时，用国内源补装（三个容器都装）
for c in aiagent-backend aiagent-celery-worker aiagent-celery-beat; do
  docker exec $c pip install -i https://mirrors.aliyun.com/pypi/simple/ \
    --trusted-host mirrors.aliyun.com -r /app/requirements.txt
done

# 4. 迁移：先看当前版本，破坏性迁移用 stamp（勿盲目 upgrade，见上方警告）
docker exec aiagent-backend sh -c "cd /app && alembic current"

# 5. 重启后端使代码生效并验证
docker compose -f docker-compose.prod.yml restart backend
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8037/docs   # 期望 200

走 2B 热更新的改动只在容器可写层，docker compose up/重建容器会丢失；条件允许时仍应配好国内镜像走 2A 正式重建。

数据库备份

A. 容器内 MySQL（本指南默认）：

docker exec aiagent-mysql mysqldump -u root -p<密码> agent_db > agent_db_backup.sql

B. 外部腾讯云 CloudDB（本项目实际用法，无 aiagent-mysql 容器）： 直连外部实例：

mysqldump -h gz-cynosdbmysql-grp-xxx.sql.tencentcdb.com -P 24936 \
  -u root -p<密码> agent_db > agent_db_backup.sql
# 若本机没装 mysql 客户端，可借用 mysql 镜像执行：
# docker run --rm mysql:8.0 mysqldump -h <外部地址> -P 24936 -uroot -p<密码> agent_db > agent_db_backup.sql

# 定时备份（crontab，每天凌晨 2 点）
# 0 2 * * * mysqldump -h <外部地址> -P 24936 -uroot -p<密码> agent_db > /home/renjianbo/aiagent/backups/agent_db_$(date +\%Y\%m\%d).sql

数据库恢复

# 容器内 MySQL
docker exec -i aiagent-mysql mysql -u root -p<密码> agent_db < agent_db_backup.sql

# 外部腾讯云 CloudDB
mysql -h gz-cynosdbmysql-grp-xxx.sql.tencentcdb.com -P 24936 -u root -p<密码> agent_db < agent_db_backup.sql

---

七、腾讯云特定配置

腾讯云 MySQL（TDSQL-C / CDB）

如果使用腾讯云数据库（不启用容器内的 MySQL），修改 backend/.env：

DATABASE_URL=mysql+pymysql://root:<密码>@gz-cynosdbmysql-grp-xxx.sql.tencentcdb.com:24936/agent_db?charset=utf8mb4

并在 docker-compose.prod.yml 中注释掉 mysql 服务，修改 backend 的 depends_on 移除 mysql 依赖。

腾讯云 COS 对象存储（文件上传）

如需将上传文件存储到 COS，在 .env 中配置：

# 待项目支持 COS 适配器后启用
# COS_BUCKET=your-bucket-1234567890
# COS_REGION=ap-guangzhou
# COS_SECRET_ID=xxx
# COS_SECRET_KEY=xxx

SSL/HTTPS 配置

建议在 Nginx 前端容器前加一层反向代理或使用腾讯云 CLB：

方案一：腾讯云 CLB + SSL 证书

1. 在腾讯云申请免费 SSL 证书
2. 创建 CLB 监听 443 端口，绑定证书
3. 后端转发到服务器 8038 端口

方案二：Nginx 直接配置 SSL

修改 frontend/nginx.conf，添加 SSL 配置后用 docker compose restart frontend 生效。

server {
    listen 443 ssl;
    ssl_certificate     /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;
    # ... 其余配置不变
}

腾讯云监控告警

Prometheus + Grafana 已内置。如需接入腾讯云监控：

1. 在 Grafana 中配置腾讯云监控数据源
2. 导入腾讯云预设面板（CVM、MySQL、CLB 等）

---

八、卸载

bash uninstall.sh

脚本会交互式确认：

• 是否删除所有容器
• 是否删除数据卷（MySQL/Redis/工作区/日志）
• 是否删除构建的镜像

完全卸载后，/opt/aiagent 目录和 backups/ 目录需手动删除。

---

九、故障排查

容器无法启动

# 查看所有容器状态
docker compose -f docker-compose.prod.yml ps

# 查看具体容器日志
docker logs aiagent-backend --tail 50

# 检查磁盘空间
df -h

# 检查内存
free -h

数据库连接失败

容器内 MySQL：

docker exec aiagent-mysql mysqladmin ping -h localhost
docker logs aiagent-mysql --tail 30

外部腾讯云 CloudDB（本项目实际用法）： 从 backend 容器内验证能否连通外部库：

docker exec aiagent-backend python -c "import os,re,pymysql; \
u=os.environ['DATABASE_URL']; m=re.match(r'.*://([^:]+):([^@]+)@([^:]+):(\d+)/([^?]+)',u); \
pymysql.connect(host=m.group(3),user=m.group(1),password=m.group(2),port=int(m.group(4)),database=m.group(5)); \
print('DB OK')"

排查点：.env 的 DATABASE_URL 是否正确、腾讯云 CloudDB 安全组是否放行了本服务器的出口 IP、账号密码是否有效、库 agent_db 是否存在。

DeepSeek API 返回 401

确认 .env 中 DEEPSEEK_API_KEY 已正确配置，密钥未过期。

Elasticsearch 无法启动

# 检查 vm.max_map_count
sysctl vm.max_map_count
# 应该 >= 262144

# 如果值不对
sudo sysctl -w vm.max_map_count=262144

Celery 任务未执行

# 确认 Redis 可用
docker exec aiagent-redis redis-cli ping
# 应返回 PONG

# 查看 Celery worker 日志
docker logs aiagent-celery-worker --tail 50

---

十、目录结构（生产环境相关）

/opt/aiagent/
├── backend/
│   ├── .env                  # 环境配置（核心）
│   ├── Dockerfile             # 后端镜像
│   ├── init.sql               # 数据库初始化脚本
│   └── requirements.txt       # Python 依赖
├── frontend/
│   ├── Dockerfile             # 前端镜像
│   ├── nginx.conf             # Nginx 配置
│   └── nginx-main.conf        # Nginx 主配置
├── docker-compose.prod.yml    # 生产环境编排
├── install.sh                 # 一键安装
├── upgrade.sh                 # 升级脚本
├── uninstall.sh               # 卸载脚本
├── prometheus.yml             # Prometheus 采集配置
├── grafana/
│   ├── datasources/           # 数据源配置
│   └── dashboards/            # 监控面板 JSON
└── filebeat/
    └── filebeat.yml           # 日志采集配置