概览 · 这套系统怎么搭
AperturePrism 由 api + 若干 worker + web 组成，底层依赖 PostgreSQL（含 pgvector）与 Redis。简单说需要准备四类东西：
- 基础设施：一台能跑 Docker 的主机、PostgreSQL + pgvector、Redis。
- GitHub 接入：一个 GitHub App（用于读仓库、发评论 / Review）+ 可选 GitHub OAuth App（用于 WebUI 登录）。
- 模型凭据：你自配的任一 OpenAI 兼容 API（自己的中转 / 厂商官方接口），以及一个加密主密钥。
- 可选外围：QQ 机器人网关注册、告警 Webhook 等。
模型不绑定
项目不绑定任何特定模型或厂商。模型由你自配的 OpenAI 兼容 API 驱动，在「模型路由」配置 Provider 后即可。
一、选择安装方式
推荐用内置一键安装 CLI，也可源码本地开发。
方式 A · 一键安装（推荐）
支持源码安装与 Docker Compose 全栈安装二选一（交互选择，或 --mode 指定）。可直接从 GitHub 直跑，无需先 clone：
常用参数：
--mode=source|compose：指定安装方式（1=源码，2=Docker 全栈）。--yes：跳过交互确认。--auto-install：缺失 Node / Docker 时自动安装（需 root/sudo）。--skip-docker/--skip-deps/--skip-migrate：跳过对应步骤。--verify：Docker 地址池耗尽场景下叠加compose.verify.yml（见第十节）。
环境变量覆盖：APERTUREPRISM_SRC_DIR（源码目录）、APERTUREPRISM_REF（分支/标签）、APERTUREPRISM_REPO_URL（仓库地址）、APERTUREPRISM_AUTO_INSTALL=1。
方式 B · 本地开发（分步）
分别启动后端（各占一个终端）：
Web 独立 workspace：cd apps/web && npm install && npm run dev。API 在 http://127.0.0.1:30001，Web 在 http://localhost:5174。
注意
首次部署先把迁移跑完再启动应用。迁移可重入、失败可重跑。
二、准备环境文件
先复制一份环境文件并填写（密钥只放环境文件，绝不入库）：
| 变量 | 说明 |
|---|---|
DATABASE_URL / REDIS_URL | PostgreSQL（需 pgvector 扩展）/ Redis 连接串 |
HOST / PORT / LOG_LEVEL | API 监听与日志级别（默认 30001 / info） |
WEBUI_API_TOKEN | 可选 Bearer 令牌保护 WebUI API；留空则开放（仅开发/内网） |
GITHUB_APP_ID / GITHUB_APP_PRIVATE_KEY_PATH / GITHUB_WEBHOOK_SECRET | GitHub App：验签、installation token、评论发布 |
GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET | WebUI 登录；回调必须指向本实例 |
MODEL_PROVIDER_BASE_URLS | Provider → OpenAI 兼容 baseUrl 的 JSON 映射 |
CREDENTIAL_MASTER_KEY | AES-GCM 主密钥：解密 provider 密钥 / 记忆与专家团队模型调用 |
DEFAULT_LLM_MODEL | 安装向导预填的模型名（默认 gpt-4o-mini，按你的网关实际可用模型改） |
EMBEDDING_BASE_URL / EMBEDDING_API_KEY / EMBEDDING_MODEL | 与 review 模型独立配置（默认 nvidia/nemotron-3-embed-1b，2048 维） |
QQ_BOT_PROTOCOLS | NTQQ 网关 JSON（onebot11 / satori / milky） |
QQ_OFFICIAL_APP_ID / QQ_OFFICIAL_APP_SECRET / 网关 / Intents | 官方开放平台 api-v2 |
ALERT_WEBHOOK_URL | 告警 Webhook（飞书/钉钉/自定义），可在 WebUI 覆盖 |
生成一个随机主密钥：
三、接入 GitHub
GitHub App（读取与发布）
在 GitHub 创建一个 App，授权它读取你的仓库，把 APP_ID、私钥文件路径与 WEBHOOK_SECRET 填入环境文件。App 用于：
- 签发 installation token 读取仓库 / Issue / PR 内容；
- 发布评论、PR Review、Check Runs 与标签（幂等）。
App 的 Webhook 指向本实例：https://<你的域名>/github/webhook。若想接收 issue 评论事件，需在 GitHub 侧自己配置 Webhook（App 无 Webhooks 管理权限时需手动指到该地址）。
WebUI 登录（可选 OAuth）
想用 GitHub 账号登录控制台，就再建一个 OAuth App，配置回调（Authorization callback URL）为：
线上走域名/反代时用对应域名（如 https://review.example.com/auth/callback），必须与注册的回调一致。若回调指向别的域名，本地授权后的 code 会送错地址导致 state 校验失败。
Bearer 令牌（可选）
不配 OAuth 时，可设 WEBUI_API_TOKEN，接口用 Authorization: Bearer <token>（或 SSE ?token=）访问。
四、配置模型
LLM Provider（OpenAI 兼容）
在「数据与运维 → 模型路由」配置 Provider（baseUrl + API Key + 模型名），或通过 MODEL_PROVIDER_BASE_URLS 预置：
baseUrl 必须包含 /v1，adapter 会追加 /chat/completions。配置 Provider 后，model_role_policies 表会给对应角色写入 candidates 候选。角色策略包括：
issue_analysis— Issue 分析；pr_review— PR 审查；duplicate_judgment— 重复裁决；expert_review— 专家团队（可选）；memory_consolidation— 记忆合并（可选）；spam_detection— 垃圾识别。
想启用切换故障转移，可让每个角色的 candidates 同时列出主、备两个 Provider（主在前）。worker 每次任务都从数据库读策略，改动即时生效，无需重启。
API Key 加密存储
Provider 的 key 不放在 .env，而是经 AES-GCM 加密存 provider_accounts，worker 用 CREDENTIAL_MASTER_KEY 解密（见第二节）。
嵌入模型（独立配置）
向量召回用独立嵌入配置：
默认 nemotron-3-embed-1b（2048 维）。注意：向量只用于召回，重复等最终裁决由服务端策略完成。
五、WebUI 初始化
- 首次打开进入
/setup安装向导：检测环境并一键初始化（管理员）。 - 首个通过 OAuth 登录的用户自动成为管理员；可到「用户管理」切换角色。
- 「数据与运维 → 仓库」同步 GitHub App 安装的仓库（
POST /repositories/sync，后台每 12 小时自动拉取），再在仓库页手动触发一次分析验证链路。 - 配置好 Provider 后，在「已安装仓库」页下拉选择最近 open 的 Issue / PR 手动触发，任务状态变为
completed即链路正常。
验证链路
手动触发一次分析 → 任务 completed、GitHub 出现评论，即代表 Webhook/模型/发布全链路已通。
六、能力开关
| 能力 | 在哪开 |
|---|---|
| Issue 自动指派 / 标题改写 / 自动打标 | 系统配置（issue_auto_assign / issue_rewrite_title / 标签规则） |
| PR 自动审查 / Check Runs | 系统配置（pr_auto_review / pr_check_run） |
| 仓库扫描 | 「数据与运维 → 仓库扫描」：全局开关 + 逐仓库配置，自动建分析任务 / 可选建跟踪 Issue |
| 标签配置 | 「数据与运维 → 标签配置」：三要素表单（字段下拉 + 取值 + 标签名），不用手写前缀 |
| Agent Skills / 专家团队 | /capabilities 开关；需先配 expert_review 角色策略，未配置自动降级单模型 |
| 仓库记忆 | 分析/审查自动沉淀反思，Scheduler 定期合并回灌；记忆页可管理 |
| 安全管理 | 独立安全页：访问控制 + 速率限制 + 操作审计（/audit）+ 管理员门禁 |
运行时配置可通过 PUT /settings 热更新（约 8s 生效），无需重启。
七、QQ 机器人
在 WebUI「数据与运维 → 机器人」页配置即可（密钥留空保留）；也可在环境变量中配置：
第三方协议（NTQQ）
支持 OneBot 11 / Satori / Milky。按你的 NTQQ 客户端配置 baseUrl、gatewayUrl 与 accessToken。
官方开放平台 api-v2
默认网关 wss://api.sgroup.qq.com/websocket；Intents 默认 1<<25 启用 C2C + GROUP_AT 消息事件（33554432）。
容器内 qq-bot 默认不随全栈启动（无凭据会重启循环），需在 WebUI 配置凭据后手动以 --profile qq up -d 启动。
八、迁移 / 备份 / 恢复
迁移
自研执行器按 _journal.json 顺序执行迁移并记录，可重入。不要用 drizzle-kit migrate 应用（对无 snapshot 的手写 SQL 会静默失败）。
备份 / 恢复
建议每日备份并保留 N 份。issue_documents 可由 index-worker 重建，恢复后可选重建而非依赖其备份。
九、在线更新
- WebUI「系统配置 → 版本与更新」点击「更新到最新」：自动 pull → migrate → 重建容器 → 健康检查，失败自动回滚。
- 进度以 SSE 分阶段推送，api 重建属预期断连；完成倒计时自动刷新页面。
- 命令行方式：改
docker/.env.production的IMAGE_TAG，再pull→run --rm migrate→up -d。 - v1.0.7 之前的旧版本无法在线自更新，需手动升级一次到 v1.0.7+。
十、受限环境（override）
当 NAS 等环境无法直连 ghcr.io（TLS 握手超时）或 Docker 地址池耗尽时，叠加两个 override 文件：
docker/images-mirror.yml：用国内镜像站（如ghcr.nju.edu.cn）重写各服务镜像；新增容器服务需同步补条目。docker/compose.verify.yml：把全部服务挂到 external 网络apnet，并设AP_VERIFY=1让在线更新器使用同一组文件。
常见问题
任务反复失败 / 队列堆积，怎么办？
优先检查模型层：模型余额不足或通道异常会返回 402 / 405，导致所有任务 handler_error。确认 Provider baseUrl 可达、Key 有效，可用 GET {baseUrl}/models（带鉴权头）验证。改 model_role_policies 的 candidates 模型名即时生效。
webhook 返回 401？
校验 GITHUB_WEBHOOK_SECRET 与签名是否一致。
worker 报 authentication_failed？
校验 CREDENTIAL_MASTER_KEY 与 provider_accounts 密文是否匹配。
/health/ready 非 200？
检查 DB / Redis 容器健康与连接串；ready 返回 200 才代表 DB+Redis 均就绪。
任务一直 retry_wait 不恢复？
确认 scheduler 存活——lease/retry 由它回收释放。
GitHub 被限流？
github-adapter 已对 authentication_failed 做一次性重试；429/5xx 由 worker 重试策略处理。可检查最近 /index/status 与索引日志是否因 token 限流失败。
还没覆盖到你的场景？到 GitHub 仓库 ↗ 提 Issue。