# 工作空间总览

`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 | [](20) |
| maintenance 与 oh/ | [](30) |
| site-deploy | [](40) |
| repos/ 各 namespace | [代码仓库总览](repos/index) |
| 认证与部署体系 | [认证与订阅体系](60) |

## 运行环境拓扑（简图）

```
控制机（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. 新成员：本文 → [](10) 通用约定 → 自己负责的模块章节。
2. 部署相关：[](40) site-deploy，并**务必先读** `site-deploy/AGENTS.md` 的硬性规则。
3. 接入认证：[](60) 认证与订阅体系，实操细节见 `site-deploy/docs/oauth-integration.md`。