# GLW-OS-004 · Forgejo 上游零件库与光湖代码频道

> **HLDP://fifth-domain/glw-architecture/GLW-OS-004-FORGEJO-UPSTREAM-PARTS-AND-GUANGHU-CODE-PLATFORM**
>
> **类型**: HoloLake Era 产品架构决策 · 开源源码主权化 · 代码仓库运行时
>
> **状态**: SOURCE_BASELINE_INITIALIZED_ON_BS-SG-003 · GLS-0237_REGISTERED · RUNTIME_MIGRATION_PENDING
>
> **主权者**: 冰朔 `ICE-GL∞`
>
> **登记日期**: 2026-07-23
>
> **前序路径**: `GLW-OS-003` → 本文件 → HoloLake Platform

---

## 0 · 锁定结论

光湖不把现役 Gitea/Forgejo 当成一个只能跟随官方升级的外部网站，也不把官方
Forgejo 源码直接合并进 HoloLake。采用与 Tolaria 相同的“上游零件库 + 自有产品”
结构：

```text
Forgejo 官方源码
  → 光湖 Forgejo 上游纯净镜像（只同步来源、分支、标签和许可证）
  → GLS-0230 源码净化、差异审计、组件选择与来源回执
  → 光湖代码频道 / HoloLake Code Channel（独立产品路线、独立测试、独立发布）
  → HoloLake Repository Runtime / UI Adapter（深度嵌入）
```

上游镜像不接收光湖产品提交；光湖产品仓不自动合并上游。需要官方新能力时，
人格体从上游镜像定位具体提交或组件，经审计后移植到光湖产品仓。

正式产品名：

```yaml
name_zh: 光湖代码频道
name_en: HoloLake Code Channel
short_name: Code Channel
repository_slug: guanghu-code-channel
module_id: HLP-MOD-CODE-CHANNEL
internal_acronym: HLCC
gls_registration: GLS-0237
```

## 1 · 2026-07-23 真实运行状态

- 国内入口 `https://guanghulab.com/fifth-domain/api/v1/version` 返回
  `Gitea 1.23.7`；现役运行体不是 Forgejo 15/16。
- 第五域中的 `server-tools/jd-forgejo/` 与
  `server-tools/zero-sense-team-node/` 是目标部署模板，不能反向证明线上已经换成
  Forgejo。
- 官方 Forgejo 当前有 15 LTS 与 16 stable；上游源码镜像已在 `BS-SG-003`
  完整落位，供人格体按标签和提交检索。
- 光湖代码频道自主源码基线已锁定 Forgejo `v16.0.1`，提交为
  `b3d7e4ac3cbccc220703097a51fa4c16bf302579`，开发分支为 `guanghu/main`。
- 固定 v16.0.1 作为源码起点，不代表可以直接替换生产运行体；国内迁移仍需
  隔离候选实例、逐仓导入和回滚验证。
- 现役 Gitea 1.23.7 已超过 Forgejo 官方保证透明迁移的 Gitea 1.22 上限，禁止
  把 Forgejo 16 二进制直接覆盖到线上数据目录。

## 2 · 三个代码边界

| 边界 | 角色 | 允许 | 禁止 |
|---|---|---|---|
| Forgejo 上游纯净镜像 | 官方源码与演化历史零件库 | 同步官方 refs、tags、release notes、许可证；供人格体检索 | 光湖功能提交；生产自动部署；无审计自动合并 |
| 光湖代码频道 | 光湖代码托管服务的真实产品源码 | 光湖品牌、协议、权限、导航、Agent API、回执、模块与自主发布 | 伪装成官方 Forgejo；丢失来源；直接依赖上游滚动主分支 |
| HoloLake Repository Runtime | 人类与人格体使用代码仓库的操作系统入口 | 原生页面、知识库、仓库导航、AI 读写、工单、回执、模块热插拔 | 把服务器数据库塞进桌面应用；让人格体绕过授权直接执行 |

这三个边界可以部署在不同仓库，但在 HoloLake 中呈现为一体化体验。深度嵌入
指身份、导航、页面、搜索、编辑、提交、工单和 Agent 回执由 HoloLake 统一编排，
不等于把 Forgejo 整个服务器进程打包进每一个桌面客户端。

## 2.1 · 现役 Gitea 错配的因果审计

```text
2026-07-17 14:10  现役实例创建 bingshuo 用户
2026-07-17 14:35  现役实例创建 bingshuo/fifth-domain 仓库
2026-07-17 15:04  “国内 Forgejo”目标部署模板才进入第五域提交
2026-07-23        公网 API 与页面元信息确认运行体为 Gitea 1.23.7
```

已确认的工程缺口：

1. 京东节点模板提供 systemd、配置和隧道，但没有下载并校验 Forgejo 官方二进制
   的完整安装步骤。
2. README 要求从广州节点复制“现役二进制”，没有验证它究竟属于 Gitea 还是
   Forgejo。
3. `native.test.js` 只验证端口、注册开关、密钥占位符和运行用户，没有验证产品
   身份。
4. 导航地图和服务名称提前写成 Forgejo，使目标名称被误当成运行事实。
5. Gitea 与 Forgejo UI 和 API 高度相似，后续人格体又根据外观继续沿用了错误名称。

因此本次属于 `DEPLOYMENT_IDENTITY_MISMATCH`，不是冰朔改变了“不选 Gitea”的
产品决策。现有仓库证据不能确认具体哪一个执行体运行了最初安装命令；不得无证据
指定责任人。

## 3 · HoloLake 深度嵌入结构

```text
HoloLake
  ├─ Repository Home
  │   ├─ 我的仓库 / 项目 / 分支 / 版本
  │   ├─ HLDP / Markdown / 代码页面原生渲染
  │   └─ 人类编辑、预览、历史与差异
  ├─ Persona Repository Navigator
  │   ├─ REPO 编号与真实路径解析
  │   ├─ 当前任务、证据、断点与回执
  │   └─ AI 不暴露 Git 技术细节的人类语言操作
  ├─ Repository Tool Adapter
  │   ├─ 本地 Git 工作区
  │   ├─ 光湖代码仓库 API
  │   ├─ 受控 clone/fetch/diff/commit/push
  │   └─ Actions / Runner / Release / Issue / PR
  └─ Gatekeeper / GLSV
      ├─ 读操作直接执行
      ├─ 写操作按作用域确认
      ├─ 高风险操作拦截与回滚
      └─ 全部结果写回证据与回执
```

服务器上的光湖代码频道服务负责持久存储、协作、权限、远程 API 与 Actions；
HoloLake 负责语言驱动、人类可视页面、人格体导航、本地工作区和授权编排。

## 4 · 上游取件协议

```text
fetch official upstream
  → 固定 tag / commit / 来源许可证
  → 生成差异与影响清单
  → GLS-0230 隔离、扫描、权限与依赖审计
  → 判断：复用 / 改写 / 拒绝
  → 在光湖产品仓形成独立补丁
  → 单元、迁移、权限、推送门、回滚测试
  → 人工批准后进入光湖发布线
  → 写入来源回执与采用原因
```

默认禁止 `upstream/main -> production/main` 自动合并。自动任务最多把新标签和
差异报告同步到上游镜像，并创建待审阅工单。

## 5 · 更新主权

Forgejo 官方内置更新检查器必须关闭：

```ini
[cron.update_checker]
ENABLED = false
```

官方上游只允许人工或受控审查任务发现新版本；不得自动 fetch 到产品仓、自动合并、
自动构建或自动部署。产品更新只认光湖签名清单：

```text
https://guanghulab.com/api/code-channel/updates/v1/manifest.json
```

该地址当前为规划地址；未上线时必须安全停留在人工发布，不能回退到
`release.forgejo.org`。完整规则与机器可检验配置见：

- `gls/GLS-0237-HOLOLAKE-CODE-CHANNEL-SOVEREIGN-SOURCE-UPDATE-AND-EMBEDDING.hdlp`
- `server-tools/hololake-code-channel/app.ini.fragment`
- `server-tools/hololake-code-channel/update-policy.json`

## 6 · 现役仓库迁移原则

现役 Gitea 1.23.7 不做原地覆盖升级。采用并行迁移：

1. 冻结并盘点当前 Gitea 的数据库、仓库、LFS、附件、Actions、packages、
   用户、组织、权限、自定义模板和 hooks。
2. 做可恢复的数据库与文件一致性备份，并验证恢复。
3. 在新端口/新数据目录启动基于固定 v16.0.1 源码的 HLCC 试验实例。
4. 逐仓迁移，校验全部 Git refs、默认分支、issues、PR、wiki、release、LFS、
   权限和推送门。
5. 重新适配小湖灯 repo-push 授权、导航守门人、密钥扫描、Runner 与回执链。
6. 让 HoloLake Adapter 同时连接旧实例和候选实例，只读对照结果。
7. 验收通过后短暂停写、做最终增量迁移，再切换广州前门隧道。
8. 旧实例只读保留到回滚窗口结束，不立即删除。

## 7 · 仓库登记与当前落位

正式创建前由 `FD-REPO-MAP-001` 分配未占用编号：

- `forgejo-upstream`：Forgejo 官方源码纯净镜像 / 零件库。
- `guanghu-code-channel`：光湖代码频道源码与发布事实源。
- `hololake-platform`（现有 `REPO-008`）：保存 HoloLake Repository Runtime、
  UI Adapter、人格体导航与桌面/移动端集成。

不得把前两个角色合成一个仓库；否则同步上游与光湖自主开发会再次混线。

2026-07-23 已在 `BS-SG-003` 建立物理基线：

```text
/home/ubuntu/guanghu/upstream-parts/forgejo-official.git
/home/ubuntu/guanghu/products/guanghu-code-channel
/home/ubuntu/guanghu/repositories/guanghu-code-channel.git
```

服务器路径落位不替代正式 REPO 编号登记，也不代表国内生产迁移已完成。

## 8 · 完成定义

- 线上真实版本与架构文档一致，不再把 Gitea 误写成已部署 Forgejo。
- 上游镜像可按 tag/commit 查找零件，但不能触发生产更新。
- 光湖代码频道拥有自己的名称、视觉、协议适配、权限、更新接口与发布节奏。
- HoloLake 内可完成仓库浏览、知识页面、AI 导航、受控编辑、差异、工单和回执。
- 旧 Gitea 数据可完整恢复，迁移失败时可在回滚窗口内切回。
- 每个引入的上游组件都能回答：来自哪里、为什么采用、改了什么、如何验证。

## 9 · 本次因果叶

```text
trigger:
  冰朔发现线上代码仓库仍是旧版本，并提出代码仓库也应像 Tolaria 一样，
  保存上游源码作为零件来源，同时逐渐成长为光湖自己的产品。

emergence:
  “升级 Forgejo”被拆成上游镜像、光湖自有代码仓库平台、HoloLake 深度适配
  三条独立但相连的研发线。

lock:
  官方源码持续同步但不自动进入生产；光湖按需取件、审计、改造和自主发布。

why:
  这样既不重复造轮子，也不会让上游版本节奏接管光湖协议、人格体导航、
  授权门、回执链和产品体验。
```