plane-gptproto-integration/HANDOFF.md

交付说明 — plane-gptproto-integration

本压缩包包含 Plane v1.3.0 (AGPL-3.0 开源项目管理工具) 自部署 + gptproto.com AI 聚合 API 集成的完整代码。已脱敏,可直接交付外部团队部署。

包内容速览

plane-gptproto-integration/
├── HANDOFF.md                   ← 你正在看的这份
├── README.md                    项目简介
├── CLAUDE.md / AGENTS.md        开发期 AI 协作上下文 (可保留作技术参考)
├── docs/
│   ├── PLAN.md                  完整方案 + 后门/隐私评估
│   └── USER_GUIDE.md            给最终用户的使用说明
├── deploy/
│   ├── local/                   本地 Docker 部署 (推荐先在这跑通)
│   │   ├── .env.template        所有密钥占位符,部署前需填
│   │   ├── docker-compose.override.yml
│   │   ├── pull-plane.sh        从 GitHub 拉 Plane v1.3.0 源码 (源码已附带,通常无需运行)
│   │   ├── README.md            本地部署详细步骤
│   │   └── src/                 Plane v1.3.0 上游源码 (已随包附带,离线可部署)
│   └── remote/                  生产部署 (1Panel + OpenResty 反代 + 自签 SSL)
│       ├── .env.template
│       ├── docker-compose.override.yml
│       ├── install.sh           生产一键安装脚本
│       ├── plane.conf           OpenResty 反代配置
│       ├── tdb.js               前端注入脚本
│       └── README.md
├── ai-agent/                    FastAPI AI 聚合服务源码
│   ├── ai_agent/main.py         4 个端点: /healthz /ai/create-issue /ai/summarize /ai/search
│   ├── Dockerfile
│   ├── requirements.txt
│   └── tests/                   pytest TDD 用例
├── plane-dashboard/             自定义前端 (React + Vite + Semi UI)
│   ├── src/                     源码
│   ├── dist/                    预编译产物 (可直接 docker build 不必本机 npm install)
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
└── qa/
    ├── verify-local.sh          6 项健康检查
    └── checklist.md

已脱敏

• ✅ 所有真实密钥/Token 已剔除,deploy/*/.env.template 全部为 CHANGEME_* 占位符
• ✅ 生产服务器 IP 已替换为占位符 YOUR_SERVER_IP
• ✅ docker-compose 中的本机绝对路径已改为相对路径 (../../ai-agent、../../plane-dashboard)
• ✅ __pycache__ / .venv / node_modules / .DS_Store / .omc 已剔除

反遥测 / 反回拨锁定 (LOCKDOWN) ★ 必读

Plane v1.3.0 默认有几个"回拨家里"通道,本包已用 env-gated 开关全部封堵。 设计原则: 不动上游业务代码逻辑,只在 1 个文件加 2 处 if 守卫,通过 .env 里的开关控制开关。 升级 Plane 时几乎不会和上游冲突,改动可审计、可一键还原。

通道	默认状态	已采取的措施
OpenTelemetry → telemetry.plane.so (每 6 小时 + 启动各一次,发送 instance_id / 用户数 / issue 数等)	上游默认 开	(1) register_instance.py 新建 Instance 时根据 env DISABLE_TELEMETRY=1 把 is_telemetry_enabled 置 False (2) tracer.py 上游本身的 if instance.is_telemetry_enabled: 守卫会直接跳过上报逻辑 (3) 防御纵深: OTLP_ENDPOINT=http://127.0.0.1:1 让 exporter 连黑洞
GitHub release 检查 → api.github.com/repos/makeplane/.../releases/latest (启动一次)	上游默认 开,无 env 关	register_instance.py 的 check_for_latest_version() 加 env 守卫: DISABLE_GITHUB_VERSION_CHECK=1 时直接返回 fallback,后面 try/requests.get 流程保留(便于将来想恢复)
PostHog 事件追踪 → 用户邀请/工作区删除等	关 (需 env 配置才会发)	.env.template 显式空 POSTHOG_API_KEY / POSTHOG_HOST
Microsoft Clarity 前端会话录制 → clarity.ms	关 (需 env 配置才会发)	.env.template 显式空 VITE_SESSION_RECORDER_KEY
Intercom 客服 widget → widget.intercom.io	上游默认 开	IS_INTERCOM_ENABLED=0

代码改动只有 1 个文件,2 处新增 if 守卫(共 6 行),其他逻辑 100% 原样:

• apps/api/plane/license/management/commands/register_instance.py
• diff 在 deploy/local/patches/01-env-gated-register-instance.patch
• override.yml 通过 volumes: bind-mount 把这个 patched 文件覆盖到上游容器内的 /code/plane/... (绕过预构建镜像不能改源码的限制)

部署后如何验证 LOCKDOWN 生效

# 1. DB 里 telemetry 标志位
docker compose exec plane-db psql -U plane -d plane -c \
  "SELECT instance_id, is_telemetry_enabled FROM instances;"
# 期望: is_telemetry_enabled = f (false)

# 2. 容器内确认 env-gated 补丁已挂载
docker compose exec api grep -n "LOCKDOWN" \
  /code/plane/license/management/commands/register_instance.py
# 期望: 2 行 (check_for_latest_version 守卫 + create 默认值)

# 3. 容器里看 env 开关已注入
docker compose exec api sh -c 'env | grep -E "DISABLE_TELEMETRY|DISABLE_GITHUB"'
# 期望: DISABLE_TELEMETRY=1  DISABLE_GITHUB_VERSION_CHECK=1

想恢复上游原版行为(关闭 LOCKDOWN)?

只需在 .env 里把 DISABLE_TELEMETRY=0 和 DISABLE_GITHUB_VERSION_CHECK=0,然后 docker compose up -d --force-recreate api。 代码逻辑完整无缺,不需要改源码。

快速部署 (本地 Docker)

前置: Docker Desktop ≥ 4.30,8090 / 8100 端口空闲。

# 1. 解压
unzip plane-gptproto-integration.zip
cd plane-gptproto-integration

# 2. 准备环境变量 (复制模板 → 替换所有 CHANGEME_*)
cp deploy/local/.env.template deploy/local/.env
chmod 600 deploy/local/.env
# 用你喜欢的编辑器把所有 CHANGEME_xxx 改成强随机值
# 必填项:
#   POSTGRES_PASSWORD       强密码 (随机 32 字符)
#   RABBITMQ_PASSWORD       强密码 (随机 32 字符)
#   SECRET_KEY              Django 密钥 (≥ 50 字符)
#   AWS_ACCESS_KEY_ID       MinIO 用,任意字符串
#   AWS_SECRET_ACCESS_KEY   MinIO 用,任意字符串
#   LIVE_SERVER_SECRET_KEY  ≥ 32 字符
#   GPTPROTO_API_KEY        gptproto.com 控制台申请
#   PLANE_API_TOKEN         留空,Plane 首次登录后在 god-mode 生成再回填
${EDITOR:-vim} deploy/local/.env

# 3. 启动
cd deploy/local
docker compose \
  -f src/deployments/cli/community/docker-compose.yml \
  -f docker-compose.override.yml \
  --env-file .env \
  up -d

# 4. 等约 30s 让 migrator 跑完,然后健康检查
bash ../../qa/verify-local.sh

# 5. 浏览器访问
#    http://localhost:8090           Plane Web
#    http://localhost:8100/healthz   AI Agent
#    http://localhost:8103           自定义 dashboard

生产部署 (Linux + 1Panel + OpenResty)

参见 deploy/remote/README.md 和 docs/PLAN.md。要点:

• 容器只绑 127.0.0.1:<port>,公网入口由 OpenResty 反代到 HTTPS
• plane.conf 反代配置已包含 HTTP/1.1 修复 (避免 uvicorn keepalive 超时)
• $http_host 必须透传 (非 $host),否则 MinIO presigned URL 会丢端口导致 CORS 失败

已知坑点 (来自原作者实战,务必读 CLAUDE.md 完整版)

1. Plane v1.3.0 compose 路径 = src/deployments/cli/community/docker-compose.yml (旧版的 src/deploy/selfhost/docker-compose.yml 已废弃)
2. macOS Docker Desktop 走系统代理会导致 TLS 失败: Settings → Resources → Proxies → Manual 但全留空 → Quit (非 Restart) → 重开
3. gptproto 的 claude-sonnet-4-6 当前 60s timeout 不可用,改用 claude-sonnet-4-5-20250929 或 claude-haiku-4-5-20251001
4. 改 .env 后 plane-ai 容器要 up -d --force-recreate plane-ai,普通 restart 不彻底
5. 生产路径上禁用 rsync --delete (会清掉服务器上的 git clone 的 src/)

端口规划速查

服务	本地端口	生产容器内	生产对外 (经 OpenResty)
Plane Web (proxy)	8090	127.0.0.1:8092	YOUR_SERVER_IP:8445 (HTTPS)
AI Agent (FastAPI)	8100	127.0.0.1:8101	YOUR_SERVER_IP:8446 (HTTPS)
自定义 dashboard	8103	127.0.0.1:8103	YOUR_SERVER_IP:8445/dashboard/
Postgres / Redis / MinIO / RabbitMQ	仅 docker 网络	仅 docker 网络	-

许可证

• Plane 上游源码: AGPL-3.0 (见 deploy/local/src/LICENSE.txt)
• 本集成代码: 内部使用,请按贵团队规定处理

联系/反馈

部署遇到问题,优先看 CLAUDE.md 的"非显然坑点"一节——基本覆盖了实战中遇到的所有陷阱。