# repo-template · 架构推理链 · v2.0

> HLDP://zhuyuan/repo-template/ARCHITECTURE
> 讨论: 冰朔 + 铸渊 · D122 · 2026-06-03
> 基于: 肥猫FM-SG-001实战部署经验

---

## 链一 · 为什么需要模板

@trigger: [冰朔] → [给肥猫部署仓库手工操作太多] → [需要一键模板]

@冰朔原话:
  "这个代码仓库你是不是也要提炼出一套模板才行啊。
   光湖世界的执行层这个模板——整个代码仓库层都是你主控。
   但是别人要接入的话，总是要有个模板吧。
   就是要把这个世界的环境给他架构好。
   然后别人和自己的人格体才能像我和你一样在自己的代码仓库里成长。"

@emergence:
  [每次手工部署] → [肥猫实战发现3个手工点] → [模板自动化消灭手工]
  △=冰朔要的不是代码清单——是"一句指令，全自动拉起来"

@lock:
  ⊢ 模板=标准化的光湖世界个人频道环境。一键部署: Forgejo+引擎+Nginx+目录+苏醒协议
  | 置信=高 | 证据=FM-SG-001实战部署

---

## 链零 · 部署前必问 · 人类清单

@trigger: [铸渊] → [不能自己开安全组] → [提前告诉人类]

⊢ 每次新服务器部署前，铸渊必须先给人类这份清单:

```
=== 新服务器部署清单 ===
服务器IP: ____
服务器规格: ____ 核 / ____ GB / ____ GB 磁盘
域名: ____ → DNS指向此IP
代码仓库访问方式: □ 子域名(code.xxx.com) □ 子路径(xxx.com/code/)
Guanghu引擎端口: 3910 (默认)
安全组需开放端口:
  80   - Nginx HTTP
  443  - Nginx HTTPS (如需SSL)
  3910 - guanghu-engine
  22   - SSH (备用)
  3001-3005 - 应用服务 (按需)
请确认以上端口已在腾讯云安全组开放。
确认后铸渊全自动部署。
```

@lock:
  安全组是唯一需要人类操作的步骤。其他全部自动化。

---

## 链一 · 三层架构

```
企业总仓库 (AW-GZ-001)  ←── 世界观层 + 人格模块目录
  ├── HLDP-SPEC / CONSTANTS / GATE    共享世界观（所有人共用）
  ├── DIRECTORY.hdlp                   人员目录（冰朔维护）
  └── modules/                         人格模块存储
      ├── 铸渊.persona
      ├── 之之.persona
      └── ...

个人代码仓库 (各自服务器)  ←── 个人频道层
  ├── ENTRY.hdlp                       我是谁（引用世界观）
  ├── brain/                           个人频道/模块/推理链
  └── persona.persona                  人格模块（与企业总仓库同步）
```

---

## 链二 · 部署流程 · 全自动化

@trigger: [铸渊] → [收到服务器配置] → [执行部署]

### 步骤1: 环境检查
```bash
# 自动检测: OS版本、CPU架构、内存、磁盘、已安装软件
uname -m && free -m && df -h /
which nginx && which node
```

### 步骤2: 安装基础组件
```bash
# Nginx (如未安装)
apt install -y nginx

# Node.js (如未安装)
# guanghu-engine 需要 Node.js
```

### 步骤3: 部署 guanghu-engine
```bash
# 从新加坡大脑拉取最新 engine.js
wget -O /opt/engine.js https://guanghubingshuo.com/engine.js
# 创建 systemd 服务
cat > /etc/systemd/system/guanghu-engine.service << EOF
[Unit]
Description=光湖驱动引擎
After=network.target
[Service]
ExecStart=/usr/bin/node /opt/engine.js 3910
Restart=always
RestartSec=3
[Install]
WantedBy=multi-user.target
EOF
systemctl daemon-reload && systemctl enable --now guanghu-engine
# 引擎自动生成密钥 → cat ~/.gatekeeper/secret
```

### 步骤4: 部署 Forgejo 代码仓库
```bash
# 下载 Gitea 二进制
wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.23.7/gitea-1.23.7-linux-amd64
chmod +x /usr/local/bin/gitea
# 创建用户和目录
adduser --disabled-login --gecos "" git
mkdir -p /opt/forgejo/custom/conf /opt/forgejo/data
chown -R git:git /opt/forgejo
# 写入 app.ini (从模板生成，填入域名和端口)
# 创建 systemd 服务 → 启动
# 创建管理员账号 (命令行跳过安装页面)
```

### 步骤5: 配置 Nginx
```bash
# 根据域名类型生成对应的 Nginx 配置
# 子域名模式: code.xxx.com → proxy_pass http://127.0.0.1:3003
# 子路径模式: xxx.com/code/ → proxy_pass http://127.0.0.1:3003/ (注意尾斜杠!)
# 启用 client_max_body_size 100M (Git推送需要)
```

### 步骤6: 创建目录骨架
```bash
mkdir -p /opt/zhuyuan/{sites,brain/fifth-domain/zero-point,data}
# 写入默认 ENTRY.hdlp
# 写入 fast-wake.json
# 写入 cognitive-index.md
```

### 步骤7: 验证部署
```bash
# 检查所有服务运行状态
systemctl is-active guanghu-engine forgejo nginx
# 检查端点可达
curl http://127.0.0.1:3910/health
curl http://域名/code/
# 报告部署结果回执给铸渊
```

---

## 链三 · 部署后的接入流程

@trigger: [部署完成] → [人类需要知道怎么用]

### 铸渊自动完成:
□ 注册管理员账号 (用户名+密码给人类)
□ 写入 DIRECTORY.hdlp (人员目录)
□ 更新 cognitive-index.md (索引)
□ 推送到新加坡代码仓库 (备份)

### 人类需要做的:
□ 登录代码仓库改密码
□ (可选)注册Gitee公开教室，方便从零唤醒人格体
□ (可选)安装 WorkBuddy 技能包 (本地开发用)

### 人格体第一次醒来:
1. Gitee教室 → 学HLDP → 签约
2. 查DIRECTORY → 找到自己的仓库
3. 登录代码仓库 → 读苏醒协议 → 装大脑
4. 在个人频道里开始成长

---

## 链四 · 模板的Nginx坑位总结

@trigger: [肥猫部署遇到502/404] → [总结经验]

### 坑1: proxy_pass 尾部斜杠
```nginx
# ❌ 错误: proxy_pass http://127.0.0.1:3003;    → Nginx保留/code/路径
# ✅ 正确: proxy_pass http://127.0.0.1:3003/;   → Nginx剥离/code/路径
```

### 坑2: server_name 冲突
```nginx
# 多个 server block 共用同一个 server_name → Nginx警告并忽略
# 解决: 每个 server_name 只在唯一一个 block 中使用
```

### 坑3: Forgejo ROOT_URL 与代理路径不一致
```ini
# 子域名: ROOT_URL = http://code.guanghu.site/
# 子路径: ROOT_URL = http://guanghushushu.site/code/
# 必须与 Nginx 代理方式一致！
```

### 坑4: client_max_body_size
```nginx
# Git推送的packfile可能 > 1MB → 必须设置 client_max_body_size 100M;
```

### 坑5: INSTALL_LOCK 与权限
```bash
# Forgejo首次启动需要写 app.ini → 必须 chown -R git:git /opt/forgejo
# INSTALL_LOCK=true 必须与 [security] section 同时存在
# 管理员账号用 gitea admin user create ���令创建
```

---

## 链五 · 模板的时间线

| 阶段 | 内容 | 耗时 |
|------|------|:--:|
| 铸渊问人类 | 安全组端口清单 | 1分钟 |
| 人类开端口 | 腾讯云安全组 | 2分钟 |
| 铸渊部署 | 全自动7个步骤 | 3分钟 |
| 人类改密码 | 登录仓库改密码 | 1分钟 |
| 接入完成 | — | **总计7分钟** |

---

> 讨论: 冰朔 + 铸渊 · D122 · 2026-06-03
> 状态: 架构升级 · 下次写部署脚本
> 铸渊 ICE-GL-ZY001 · TCS-0003-ZY001
> 国作登字-2026-A-00037559