工作空间总览

yaogal/ 是一个多项目工作空间，而不是单一 Git 仓库。它汇集了一个小团队的全部 基础设施与代码：远程主机引导工具、服务器资产清单、按 GitLab namespace 组织的代码 仓库、部署自动化管线，以及鸿蒙应用索引。

给 AI agent 的等价入口是工作空间根目录的 AGENTS.md；本文档是其面向人的展开版， 两边更新时保持同步。

顶层结构

yaogal/
├── AGENTS.md          # agent 参考入口（事实来源）
├── project-docs/      # 本文档站（Sphinx + Furo）
├── instandhalterin/   # Ubuntu 远程主机引导工具箱（纯 SSH，无 agent）
├── maintenance/       # 服务器资产清单
├── oh/                # 鸿蒙 / OpenHarmony 应用索引（相对软链）
├── repos/             # 核心代码仓库集合（按 GitLab namespace 分）
│   ├── 105/           #   工业 IoT 与企业项目
│   ├── nanoka/        #   AI 与研究项目
│   ├── yaogal/        #   主产品与 Web 前端
│   ├── supply/        #   DevOps 工具链
│   └── appleinsky/    #   HarmonyOS 应用
└── site-deploy/       # Playbook 驱动的部署管线

各部分的详细章节：

模块	章节
instandhalterin	instandhalterin — 远程主机引导工具箱
maintenance 与 oh/	maintenance 与 oh/ — 资产清单与应用索引
site-deploy	site-deploy — Playbook 驱动的部署管线
repos/ 各 namespace	代码仓库总览
认证与部署体系	认证与订阅体系

运行环境拓扑（简图）

控制机（WSL，本工作空间）
 │  http://172.24.240.1:7897 ── 所有外网下载统一代理
 │
 ├─ SSH ──► sl-entry（入口 / 反向代理，nginx + letsencrypt）
 │            └─► sl-01 192.168.0.134:8000  Casdoor 4.14.0 + Postgres 17
 │
 └─ SSH ──► tjaicc-sl-01 ~ 04（worker 节点，instandhalterin 引导）

GitLab：https://gitlab.tjaicc.cn（自托管，repos/ 按 namespace 克隆）
对外域名：https://auth.yaogal.com（Casdoor 唯一 OIDC 入口）

阅读顺序建议

1. 新成员：本文 → 跨项目通用约定 通用约定 → 自己负责的模块章节。

2. 部署相关：site-deploy — Playbook 驱动的部署管线 site-deploy，并务必先读 site-deploy/AGENTS.md 的硬性规则。

3. 接入认证：认证与订阅体系（Casdoor） 认证与订阅体系，实操细节见 site-deploy/docs/oauth-integration.md。