Monorepo 总览

cikio 的全部代码集中在一个 pnpm workspace 仓库 cikio-monorepo（GitHub 私有仓库）。每个子项目是独立的部署单元，仓库层面只提供依赖管理、统一命令与 CI 门禁。

一、布局

目录	职责	部署单元
`shared/`	共享包 `@cikio/types`、`@cikio/utils`、`@cikio/moderation`，源码直出	无（不部署）
`authserver/`	统一认证中心	Worker `cikio-authserver` → authserver.cikio.cn
`ccu/`	CCU 主站（资产库、工程工坊、站内文档、问卷、公告）	Worker `cikio-ccu` → ccu.cikio.cn
`message/`	统一消息中心	Worker `cikio-message` → message.cikio.cn
`forum/`	社区站（讨论、板块、治理）	Worker `cikio-forum` → forum.cikio.cn
`docs/`	本站（对外文档站，纯静态）	Worker `cikio-docs` → docs.cikio.cn
`dev-docs/`	仓库内部开发文档（设计稿、迁移说明）	无（不部署、不参与构建）

pnpm-workspace.yaml 的 packages 列出了全部工作区成员，含 shared/packages/* 这个通配。

二、环境要求

项	要求
Node.js	`>= 22.12.0`（根 `package.json` 的 `engines`）
pnpm	11（根 `package.json` 的 `packageManager` 已钉住具体版本，CI 用同一版本）
账号	Cloudflare 账号（部署与本地访问远程资源时需要）

pnpm install

三、命令

根目录脚本（pnpm -r 递归到全部工作区成员）：

命令	作用
`pnpm install`	安装全部子项目依赖，生成唯一一份根 `pnpm-lock.yaml`
`pnpm typecheck`	递归类型检查
`pnpm build`	递归构建
`pnpm dev:<子项目>`	起某子项目的开发服务器（`dev:authserver` / `dev:ccu` / `dev:message` / `dev:forum`）
`pnpm deploy:<子项目>`	部署某子项目（等价于 `pnpm --filter <包名> run deploy`）

单子项目操作统一用 pnpm --filter <包名> run <脚本>：

pnpm --filter cikio-ccu run dev
pnpm --filter cikio-ccu run typecheck
pnpm --filter cikio-ccu run deploy      # 注意：必须带 run

部署必须由子项目目录发起：各子项目的 wrangler.toml 就在子目录内， pnpm --filter ... run deploy 已经保证工作目录正确，不要自己在错误目录里敲 wrangler deploy。

四、构建语义

各子项目的 build 含义并不一致，别把「构建通过」当成「已上线」：

子项目	`build` 实际做的事	产物
`shared/`	无 build 脚本	无（源码直出）
`authserver/`	`wrangler deploy --dry-run`：部署预检	无本地产物
`ccu/`、`forum/`	`astro build`	`dist/client`（静态）+ `dist/server`（Worker 入口 `entry.mjs`）
`message/`	`vite build`（前端 SPA）	`dist/`，由 Worker 以 Static Assets 托管
`docs/`	同步内容 + `astro build`	`dist/`，纯静态

五、依赖与 `allowBuilds`

pnpm v11 默认拦截依赖的 postinstall 脚本，未放行的包其构建脚本不会执行。 workerd、esbuild、sharp 靠 postinstall 下载平台二进制，被拦截会导致 wrangler、astro build 直接跑不起来。放行清单在根 pnpm-workspace.yaml：

allowBuilds:
  esbuild: true
  sharp: true
  workerd: true

pnpm install 报 ERR_PNPM_IGNORED_BUILDS 时，把报错里的包名按同样格式追加到根配置再重跑。这是工作区级设置，只能写在根 pnpm-workspace.yaml，不要写进子项目。

六、提交纪律

子包加/改依赖时，必须一并提交根 pnpm-lock.yaml。 CI 用 pnpm install --frozen-lockfile，只提交子目录会让 CI 两个 job 全红。
只 git add 自己要改的路径，不要用 git add -A：仓库根会不定期出现别的团队的设计文档草稿，一把梭会把它们裹进你的提交。
机密、Token、账号 ID、数据库 ID 一律不进仓库（见下一节）。
跨子项目的边界改动，先改文档（如 forum/docs/boundary.md）再改代码。

七、CI

.github/workflows/ 下有两个工作流，职责不同：

工作流	触发	做什么
`ci.yml`	push 到 `main`、所有 PR	`typecheck` job（`pnpm typecheck`）+ `build` job（`pnpm build`，并校验 `ccu/dist` 产物）
`deploy-docs.yml`	push 到 `main` 且改动 `docs/**`、`pnpm-lock.yaml` 或自身；也可手动触发	构建并部署文档站

要点：

CI 不含部署（deploy-docs.yml 除外，它只部署 docs）。CI 绿 ≠ 已上线。
ci.yml 开了 cancel-in-progress: true，所以部署任务不能和它放一起 —— 上传中被取消会留下半成品。
deploy-docs.yml 刻意关掉 cancel-in-progress，并用路径过滤避免无关改动重发整站。

八、上线口径

Cloudflare 侧没有接 GitHub 自动构建（文档站除外），其余站点的上线动作是本地执行：

pnpm --filter cikio-authserver run deploy
pnpm --filter cikio-ccu run deploy
pnpm --filter cikio-message run deploy
pnpm --filter cikio-forum run deploy

三条必须记住的规则：

数据库迁移先于部署。 库里结构没到位就部署，Worker 起来就会在查询处崩。先 db:migrate，再 run deploy。
commit sha 不等于线上版本。 核对线上跑的是哪一版，用 Version ID：
终端窗口
```
pnpm --filter cikio-ccu exec wrangler deployments list --name cikio-ccu
```
回退与灰度走 wrangler：wrangler rollback <version-id> 回退，wrangler versions deploy 做灰度。

对外访问一律用 *.cikio.cn 自定义域：*.workers.dev 在国内被 DNS 污染/屏蔽，本地验证也不要用它。

九、机密与环境变量

类别	放在哪
非机密配置（服务地址、公开客户端 ID）	各子项目的 `wrangler.toml` 的 `[vars]`（进版本控制，任何人不该往这里写机密）
机密（签名密钥、第三方 client secret、邮件 API Key）	Cloudflare 侧：`wrangler secret put <键名>` 或 Dashboard 的运行时环境变量

规则：

机密只存在于 Cloudflare 与各人本地的环境里，不写进仓库、不写进文档、不进聊天记录。
每个子项目需要哪些键名，看它自己的 wrangler.toml 注释与代码里的 Env 类型定义，或者该子项目的开发说明页（本分区各页只写键名与用途，不写值）。
本地开发用 wrangler dev 时，缺失的机密按需自行配置；不要把本地的 .dev.vars 提交上去。

十、新增一个子项目

建目录与 package.json（含 dev / build / typecheck / deploy 脚本），
根 pnpm-workspace.yaml 的 packages 追加该目录，
根 package.json 追加 dev:<名> / deploy:<名> 快捷脚本，
pnpm install 更新根 pnpm-lock.yaml 并一并提交，
在本页「布局」表与开发文档索引里补一行。

相关：各子项目开发说明、团队文档协作规范、开发问题与踩坑记录。