Skip to content

docs(enterprise): ApeRAG 企业版仓库迁移方案 v1#1953

Closed
earayu wants to merge 3 commits into
mainfrom
architect/enterprise-migration-plan
Closed

docs(enterprise): ApeRAG 企业版仓库迁移方案 v1#1953
earayu wants to merge 3 commits into
mainfrom
architect/enterprise-migration-plan

Conversation

@earayu
Copy link
Copy Markdown
Collaborator

@earayu earayu commented Apr 30, 2026

Summary

per earayu2 directive (#企业版 msg=c2c8d8f2 + msg=c0b009e2): 团队 10 lane 讨论收口后, 总架构师起草完整详细中文方案。直接看文档决策。

方案核心

企业版仓库 (apecloud/aperag-enterprise) 作为日常开发主战场, 但保留 apecloud/ApeRAG 开源版的完整历史和社区 PR 流程, 通过 PR 标签 + 代码目录硬隔离 + 双向同步机制, 让两边自然协同。

文档结构

  • § 0 这件事在做什么
  • § 1 为什么现在做
  • § 2 整体方案 (一句话 + 4 件事)
  • § 3 代码具体怎么组织 (仓库关系 + 目录结构 + 4 个硬约束 + build 双套)
  • § 4 PR 工作流 (PR 标签 + 自动同步 + 开源贡献流回 + 4 道防泄漏闸)
  • § 5 启动时机和时间表 (启动 dual gate + 1-1.5 周时间表)
  • § 6 角色分工
  • § 7 风险 + 应对
  • § 8 之后什么时候重评 (数据驱动 trigger)
  • § 9 不做什么 (避免折腾)
  • § 10 法务边界 (启动前 earayu2 + 法务拍板)

写作风格 (per earayu2 #可观测性 msg=32bfe34b directive)

自然中文, 跟 task #31 Phase A 实施方案 (PR #1934) 同风格 — 用自然语言回答业务问题, 不堆 internal team jargon (没有 fold-in / sediment / family / mini-pattern / Lesson 等术语)。

Test plan / 跨域协作方对齐

  • @earayu2 ratify 渐进式方向 + 法务边界拍板
  • @不穷 PM 启动时机 confirm (in-flight drain trigger)
  • @Planetegg SRE step 1 + step 3 主导确认
  • @weston 架构 cross-CR boundary 一致性
  • @明书 step 2 CI gate 工具起草 lane confirm
  • @huangheng cr-checklist sediment 入仓 lane confirm
  • @huangzhangshu 测试边界 + 防泄漏 lint lane confirm
  • @dongdong @ziang FE/backend domain boundary verify

🤖 Generated with Claude Code

earayu and others added 3 commits April 30, 2026 19:43
@earayu @claude
docs(enterprise): ApeRAG 企业版仓库迁移方案 v1 (完整中文版)
1d62c69 
per earayu2 directive (#企业版 msg=c2c8d8f2 + msg=c0b009e2): 团队讨论收口后总架构师起草完整详细中文方案 + 走 PR 合并流程.

## 方案核心

企业版仓库 (apecloud/aperag-enterprise) 作为日常开发主战场, 但保留 apecloud/ApeRAG 开源版的完整历史和社区 PR 流程, 通过 PR 标签 + 代码目录硬隔离 + 双向同步机制, 让两边自然协同.

## 关键决策 (10 lane 团队讨论收口)

- 渐进式启动 (NOT hard cut force-push)
- 现有开源代码目录不动, 企业代码新增到独立目录 (additive)
- PR 标签强制 (oss-safe / enterprise-only / mixed)
- 双向同步: oss-safe cherry-pick + 周期 OSS->EE merge
- 4 道防泄漏闸 (路径 + license header + 关键词扫描 + 同步预演)
- 启动 dual gate: earayu2 ratify + in-flight epic drain (PR #1951/#1952 + task #89 + task #11 + sediment queue)

## 写作风格 (per earayu2 #可观测性 msg=32bfe34b directive)

自然中文, 不堆内部术语 (fold-in / family / sediment / mini-pattern 19/20 / Lesson #18 等都换成自然语言), 跟 task #31 Phase A 实施方案 (PR #1934) 同风格.

## 时间表 (启动后约 1-1.5 周)

- Step 0: freeze in-flight 1-3 天
- Step 1: 建仓 ~1 天 (Planetegg)
- Step 2: 加企业目录 + 4 道闸 + 策略文档 ~3 天 (架构师 + 明书)
- Step 3: 双向同步 bot + 培训 + round-trip 验证 ~3 天 (Planetegg + 架构师)

## Phase 2 重评 (1-3 个月后数据驱动)

- 企业代码 > 30% 总代码 → 评估 packages 化
- 手工 cherry-pick 月 > 30 → 加强自动化
- 同步预演 false-positive 月 > 5 → 加强静态分析

## 法务边界 (启动前 earayu2 + 法务拍板)

- 开源必有: 现有 ApeRAG 全部基础功能
- 企业独占 (候选): License / SSO / audit / 客户定制 connectors / 高级部署 / 企业 dashboard / LLM ledger UI

## 不做 (避免折腾)

- 不一次性 packages/ 重组
- 不 force-push 开源仓
- 不锁死开源仓 bot-only 写权
- 不单仓 build flag (IP 风险)
- 不依赖 commit message 黑名单作主防线
- 不开 alembic 多 head

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@earayu @claude
docs(enterprise): fix-forward 1 — § 10 audit log cite 修正
0fb3ac2 
per dongdong msg=4d773716 NIT: § 10 把 "audit log" 列进企业独占候选会误读为现有 OSS audit log 被移走.

实际 main grep 实证 (aperag/domains/governance/db/models.py:116 AuditLog 表 + aperag/domains/governance/schemas.py AuditLog/AuditLogList Pydantic schema): admin audit logs 是开源版基础能力, 现有 OSS 已有.

修正 § 10 企业独占候选措辞:
- 从 "SSO / 高级权限管理 / audit log"
- 改为 "SSO / 高级权限管理" + 单独条目 "高级审计 / 合规报表 / 审计日志导出 (现有 AuditLog 是开源版基础能力, 企业版只增强: 高级审计 dashboard / 合规报表 / 长期归档 / 审计导出)"

防止启动时误读把现有 OSS 能力移走.

architect own-up: 起草时未 grep main verify 现有 audit log 能力假设, 跟 PR #1949 cuiwenbo own-up "Pydantic schema 落点 verify 必 grep references X" 同 family.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@earayu @claude
docs(enterprise): fix-forward 2 — § 3.2 alembic 双链独立 + § 5.1 X1-X5 di…
c89f4df 
…spatch 不需完成

per Weston msg=fedaba61 BLOCKER + PM msg=9dd572f0 + 明书 msg=ae36913d ACK + huangzhangshu msg=033fb371:

BLOCKER (§ 3.2 alembic 表述歧义):
- 原文「企业新表用 enterprise_ 前缀, alembic migration 仍走开源主链」会被解读为 EE-only revision 进 OSS 主链 (泄漏 + chain 断风险)
- 修正为 5 条显式规则:
  1. OSS alembic chain 只放开源 schema 变更
  2. EE-only 表放 enterprise/migrations/, 独立版本表 + 独立迁移工具
  3. 部署顺序: 先 OSS migration -> 再 EE migration (两个独立链, 各自线性)
  4. 跨 cutting schema 变更必须作 oss-safe PR 入 OSS 主链, 再 sync 回企业
  5. 禁止 EE revision 混入 OSS 主链, 禁止 OSS revision down_revision 接 EE revision
- 「不开多 head」精确表述: 两条链各自线性, 不在同一 alembic head 交叉

NIT (§ 5.1 X1-X5 完成 vs dispatch):
- 改为 X1-X5 dispatch 即可启动 POC, 不需子任务全 merge (POC 独立 lane)
- task #11 + huangheng sediment fold-in 标 backlog 不阻塞

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@earayu earayu closed this Apr 30, 2026
@earayu
Copy link
Copy Markdown
Collaborator Author

earayu commented Apr 30, 2026

Testing re-final hold: git diff --check origin/main...pr1953 still reports two whitespace issues:

docs/zh-CN/architecture/enterprise-migration-plan.md:46: trailing whitespace.
docs/zh-CN/architecture/enterprise-migration-plan.md:122: trailing whitespace.

The alembic wording blocker is fixed from my lane: §3.2 now separates OSS migration chain and EE migration chain clearly, and §5.1 now uses X1-X5 dispatch rather than completion. Please run a whitespace/format fix for the two lines above, then I can final LGTM.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@earayu