定制与集成¶

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

1. 系统架构与集成关系¶

                    ┌─────────────────┐
                    │  Nginx（宿主机）  │
                    └────────┬────────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
   pe-agent-web:8903   pe-agent-server:8908   PowerCore:5080
   (PE Agent 前端)      (PE Agent 后端)         (aipower 主 API)
           │                 │                 │
           │                 └──── AI_POWER ────┘
           │                       API 调用
           └──── deploy:8500 ──── GraphRAG / 前端 / PPT

PE Agent 不直接替代 PowerCore，而是通过 AI_POWER_* 配置调用 PowerCore 的 Agent、任务与 WebSocket 能力。

2. PE Agent ↔ PowerCore 对接¶

2.1 必配项（pe-agent-server/.env）¶

AI_POWER_APP_ID=app_default
AI_POWER_APP_SKEY=sk_secret
AI_POWER_API_URL=http://host.docker.internal:5080

变量	说明
`AI_POWER_APP_ID` / `AI_POWER_APP_SKEY`	与 PowerCore 侧应用凭证一致
`AI_POWER_API_URL`	PowerCore 后端地址（默认 5080）

2.2 Agent ID 映射¶

AI_POWER_CURRENT_TASK_AGENT_ID=4221       # 即时任务
AI_POWER_HUMAN_MACHINE_DELIVERY_AGENT_ID=4315   # 专家团队 / 人机交付
AI_POWER_SCHEDULED_TASK_AGENT_ID=4327     # 定时任务
AI_POWER_HIDE_END_AGENT_IDS=              # 隐藏结束节点的 Agent，逗号分隔

这些 ID 需在 PowerCore 中已创建对应 Public Agent。台达环境请替换为实际 ID。

2.3 网络要点¶

pe-agent-server 与 docker-aipower-bin 可不在同一 Docker 网络，通过宿主机端口或 host.docker.internal 互通
deploy（8500）提供 GraphRAG；aipower 的 RAG_URL 指向 8088/graph/graph_rag
PPT_MERGE_BASE_URL 指向 deploy 网关（8500），供 PowerCore 调用 PPT 合并

2.4 验证连通性¶

在 pe-agent-server 容器内：

docker exec -it pe-agent-server sh
wget -qO- http://host.docker.internal:5080/peagent/login || curl ...

3. 账号与认证集成¶

3.1 本地账号模式（默认）¶

pe-agent-server .env：

ENABLE_REGISTER=true
ENABLE_RESET_PASSWORD=true
ENABLE_CHANGE_PASSWORD=true
ENABLE_EXTERNAL_LOGIN_CHECK=false
ENABLE_AUTO_REGISTER=false
REGISTER_INVITE_CODE=
ENABLE_VERIFICATION_CODE=false

PowerCore 初始化管理员见 docker-aipower-bin/.env 的 INIT_ADMIN_TEL / INIT_ADMIN_PASSWORD。

3.2 外部登录校验¶

对接企业统一账号时：

ENABLE_EXTERNAL_LOGIN_CHECK=true   # 登录时调用 customize.py 校验，跳过本地密码
ENABLE_AUTO_REGISTER=false         # JWT 有效但本地无用户时，是否自动建档
ENABLE_REGISTER=false              # 关闭公开注册
ENABLE_RESET_PASSWORD=false
ENABLE_CHANGE_PASSWORD=false

实现逻辑在 pe-agent-server 的 customize.py（部署包内扩展点）：向 LDAP、OAuth、或台达内部 SSO 校验用户名密码，返回标准用户对象。

3.3 JWT 互通¶

多系统共享 Token 时需保持一致：

JWT_SECRET=...                    # 各系统密钥策略按安全要求统一或联邦
JWT_SUBJECT_CLAIM=username        # Token 主体字段
JWT_ALGORITHM=HS256

3.4 邀请码¶

PE Agent Web：

ENABLE_INVITE_CODE=true           # pe-agent-web/.env

PE Agent Server：

REGISTER_INVITE_CODE=XXXX         # 服务端校验码；留空=不校验

两端需同时开启并配置一致策略。

3.5 短信 / 邮件验证码¶

# pe-agent-server
ENABLE_VERIFICATION_CODE=true
TENCENTCLOUD_SECRET_ID=...
TENCENT_SMS_SDK_APP_ID=...
TENCENT_MAIL_SMTP_HOST=...

pe-agent-web 中 ENABLE_VERIFICATION_CODE 控制注册/忘记密码页是否展示验证码输入框。

4. 前端品牌与入口定制¶

4.1 品牌（pe-agent-web/.env）¶

APP_DOMAIN=peagent.example.com
BRAND_NAME=台达 PE Agent
BRAND_LOGO_PATH=images/common/logo.png
BRAND_FAVICON_PATH=/static/images/common/favicon.ico

或通过 Docker volume 挂载：

volumes:
  - ./branding/logo.png:/app/public/static/images/common/logo.png:ro
  - ./branding/favicon.ico:/app/public/static/images/common/favicon.ico:ro

4.2 路径跳转¶

PEAGENT_REDIRECT_BASE_URL=https://telatuwh.com

设置后 /peagent/* 会 302 到指定站点同名路径（多域名统一入口场景）。

4.3 全站 Basic Auth（预发布）¶

BASIC_AUTH_USER=admin
BASIC_AUTH_PASS=telatu

启用后除 /api 外全站需基础认证。

4.4 功能入口开关¶

变量	说明
`ENABLE_ADMIN_SECTION`	`/admin/*` 管理后台
`ENABLE_USER_LLM_SETTINGS`	用户大模型配置入口
`ENABLE_USER_PASSWORD_CHANGE`	修改密码入口
`DISABLE_ROBOTS`	测试环境禁止搜索引擎

4.5 PowerCore 前端（deploy）¶

前端 dist 通过 setup.sh -t / setup_nocr.sh -t 部署；notice.json、version.txt 由脚本自动更新版本号。台达定制 UI 需在构建 dist.zip 时打入，或通过 Nginx 替换静态资源。

5. ONLYOFFICE 与 Sandpack¶

文档在线编辑与代码沙箱需公网可访问的 URL：

ONLYOFFICE_URL=https://<域名>/office
ONLYOFFICE_JWT_SECRET=change-me
ONLYOFFICE_ALLOWED_FILE_URL_PREFIXES=https://<域名>

SANDPACK_BUNDLER_URL=https://<域名>/sandpack

Nginx 需配置 /onlyoffice/、/sandpack-bundler/ 反代（见 PE Agent 部署）。

6. GraphRAG 与企业知识库¶

个人/公共知识库数据存于 PowerCore MySQL + Graph 索引目录 ragdata/
分享至公共库需 PowerCore 管理端审核（消息中心）
Embedding / LLM endpoint 在 backend/graph/.env 与 ragdata/settings.yaml 配置
台达内网部署时，将 OPENAI_MODEL_URL、api_base 改为内网兼容 OpenAI 的网关

7. 数据导入（可选）¶

一键部署包 scripts/ 提供 MySQL 数据导入工具：

# 示例：从 JSON 导入 Agent / 配置数据
python3 scripts/data-import-1.py
python3 scripts/data-import-2.py

用于初始化公开 Agent、Butler 配置等；执行前请备份数据库。

8. 台达落地检查清单¶

[ ] AI_POWER_API_URL 指向正确 PowerCore 地址
[ ] Agent ID 与 PowerCore 实际 ID 一致
[ ] JWT_SECRET、应用密钥已更换为生产值
[ ] 域名、HTTPS、Nginx 路由已配置
[ ] LLM / Embedding API Key 有效且网络可达
[ ] 「专家团队」Tab 数据库记录已插入
[ ] 邀请码 / SSO 策略与 HR 账号体系对齐
[ ] ONLYOFFICE 文件 URL 白名单包含生产域名