部署与运维¶

读者对象：运维工程师
版本：v0.1 | 2026-08-13
参考：peagent-onekey-deploy 一键部署包

1. 整体拓扑¶

服务组	目录	默认端口	容器名示例
PE Agent Server	`pe-agent/pe-agent-server/`	8908 / 8906 / 8909	pe-agent-server, pe-agent-mysql, pe-agent-redis
PE Agent Web	`pe-agent/pe-agent-web/`	8903 / 8904 / 8905	pe-agent-web, pe-agent-onlyoffice, pe-agent-sandpack
PowerCore	`docker-aipower-bin/`	5080 / 3306	aipower-backend, aipower-mysql, aipower-redis
前端 + Graph	`deploy/`	8500	aipower-front

日志目录（deploy）：

deploy/logs/
├── supervisor/
├── nginx/
└── redis/

Docker 容器日志（json-file，带轮转）：

logging:
  options:
    max-size: "10m"
    max-file: "10"

2. 版本升级¶

2.1 更新包结构¶

将增量包解压为 /data/envs/update_data/：

update_data/
├── images/
│   ├── pe-agent-server.tar
│   ├── pe-agent-web.tar
│   ├── deploy-app.tar
│   ├── aipower-bin-images.tar
│   └── ...
├── pe-agent/
│   ├── pe-agent-server.env
│   ├── pe-agent-server.docker-compose.yml
│   ├── pe-agent-web.env
│   └── pe-agent-web.docker-compose.yml
├── deploy/
│   ├── backend/.env
│   ├── graph.zip
│   ├── ppt.zip
│   └── frontend/dist.zip
└── docker-aipower-bin/
    ├── .env
    └── backend/aipower

2.2 执行更新¶

cd /data/envs
chmod +x update.sh
./update.sh

update.sh 流程：

步骤	动作
1	导入 `update_data/images/*.tar`，按文件名标记需重启的服务
2	更新 pe-agent-server compose / `.env`（.env 仅追加新 key，不覆盖已有值）
3	更新 pe-agent-web
4	更新 deploy（graph/ppt/dist，保留 graph、ppt 目录下 `.env`）
5	更新 docker-aipower-bin 二进制与 `.env`

镜像与重启对应关系：

镜像 tar	重启服务
`pe-agent-server.tar`	pe-agent-server
`pe-agent-web.tar`	pe-agent-web
`documentserver.tar` / `sandpack-bundler.tar`	pe-agent-web
`deploy-app.tar`	deploy
`aipower-bin-images.tar`	docker-aipower-bin

2.3 前端 dist 热更新¶

cd /data/envs/deploy/frontend
./setup_nocr.sh -t    # 解压 dist.zip 并更新 version
cd ..
docker compose restart app

3. 日常运维命令¶

# 查看状态
docker ps -a | grep -E 'pe-agent|aipower'

# 重启单组服务
cd /data/envs/pe-agent/pe-agent-server && docker compose restart
cd /data/envs/docker-aipower-bin && docker compose restart aipower

# 查看日志
docker logs -f pe-agent-server --tail 200
docker logs -f aipower-backend --tail 200
tail -f /data/envs/deploy/logs/nginx/access.log

# 进入 MySQL（PE Agent）
docker exec -it pe-agent-mysql mysql -utelatu -ptelatu pe_agent

# 进入 MySQL（PowerCore）
docker exec -it aipower-mysql mysql -uroot -p aipower

4. 备份与恢复¶

4.1 需备份项¶

类型	路径 / 对象
PE Agent DB	Docker 卷 `pe-agent_mysql_data`
PowerCore DB	Docker 卷 `mysql-data`（aipower-bin）
Redis	`pe-agent_redis_data`、`redis-data`（按需）
用户文档	`docker-aipower-bin/backend/documents/`
上传文件	`backend/file_upload/`
SKILL	`backend/skills/`
Graph 索引	`deploy/backend/ragdata/`
配置	各目录 `.env`、`nginx*.conf`

4.2 MySQL 备份示例¶

docker exec pe-agent-mysql mysqldump -utelatu -ptelatu pe_agent \
  > backup/pe_agent_$(date +%Y%m%d).sql

docker exec aipower-mysql mysqldump -uroot -p'aipower@2026' aipower \
  > backup/aipower_$(date +%Y%m%d).sql

4.3 恢复¶

docker exec -i pe-agent-mysql mysql -utelatu -ptelatu pe_agent < backup/pe_agent_20260813.sql

恢复前停止相关服务，恢复后重启并验证。

5. 健康检查¶

检查项	命令 / 方式
容器存活	`docker ps` 状态为 Up
PE Agent API	`curl http://127.0.0.1:8908/`
PowerCore API	`curl http://127.0.0.1:5080/`
前端	`curl -I http://127.0.0.1:8500/`
GraphRAG	`curl "http://127.0.0.1:8500/graph/graph_rag?cmd=status"`
MySQL healthcheck	compose 内 `mysqladmin ping`
Redis healthcheck	compose 内 `redis-cli ping`

建议接入 Prometheus / 企业监控，对容器重启次数、磁盘使用率、MySQL 连接数设告警。

6. 日志与排障¶

6.1 常见问题¶

现象	可能原因	处理
PE Agent 无法对话	`AI_POWER_API_URL` 不可达	检查 5080 端口与防火墙
Graph 构建失败	LLM/Embedding Key 无效	检查 `graph/.env`、`settings.yaml`
登录 401	JWT 过期或密钥不一致	核对 `JWT_SECRET`、时钟同步
ONLYOFFICE 无法打开	JWT Secret 不一致或 URL 白名单	对齐 web/.env 与 compose
上传失败	`client_max_body_size` 过小	Nginx 设为 ≥ 100m
SSE 中断	代理缓冲未关	确认 `proxy_buffering off`
update 后配置未生效	`.env` 增量合并不覆盖旧值	手动编辑 `.env` 后 restart

6.2 Graph 索引重建¶

管理界面：个人知识库 → 重新构建；或 API：

curl -X POST "http://127.0.0.1:8500/graph/graph_rag?cmd=index" ...

重建前查看 构建日志（界面「日志」或 ragdata/logs/）。

6.3 磁盘清理¶

docker system prune -f          # 谨慎：清理未使用镜像
# 清理旧 Graph cache：deploy/backend/ragdata/cache/
# 清理 aipower logs：backend/logs/

7. 安全建议¶

修改所有默认密码：MySQL、Redis、JWT、INIT_ADMIN_PASSWORD
生产关闭 API 文档：API_DOCS_ENABLED=false
启用 HTTPS：Nginx + 证书（参考 nginx.pe-agent.conf SSL 注释块）
限制 MySQL/Redis 端口：仅绑定内网或 localhost
定期升级镜像：通过 update.sh 保持与安全补丁同步
Secrets 管理：.env 不入 Git，使用 vault 或运维密钥系统

8. 文档构建（培训站点）¶

培训 Markdown 位于 docs/content/，可用 MkDocs 编译：

cd docs
./build.sh          # 输出 site/
./serve.sh          # 开发模式 watch

详见 docs/README.md。