76 lines
4.9 KiB
Markdown
76 lines
4.9 KiB
Markdown
# Endor · Tabularium
|
||
|
||
Endor 文档与制图 monorepo。Tabularium 取古罗马档案馆之意。支持本地开发，并由 Gitea Actions 在 ces-control 上验证与部署。
|
||
|
||
## 本地开发
|
||
|
||
需要 Node.js 22.13+（推荐 LTS）、pnpm 11.25、Python 3.11+ 和 uv。
|
||
首次安装依赖需要访问软件包源。本地开发服务只监听 127.0.0.1。
|
||
|
||
```sh
|
||
pnpm install --frozen-lockfile
|
||
uv sync --project tools/figures --locked
|
||
pnpm dev
|
||
```
|
||
|
||
访问 http://127.0.0.1:3000 。站点无外部字体或 CDN 资源。
|
||
|
||
```text
|
||
apps/docs/ Next.js Pages Router + React + TypeScript + Tailwind CSS
|
||
content/docs/ Markdown 文档源，文件名成为 /docs/<slug> 路由
|
||
tools/figures/ 独立 Python 项目，使用 drawsvg 编程制图
|
||
```
|
||
|
||
## 命令
|
||
|
||
- `pnpm dev`：本地开发，修改 Markdown 后刷新页面即可读取新内容。
|
||
- `pnpm figures`：运行 Python 制图，更新 `apps/docs/public/figures`。
|
||
- `pnpm lint` / `pnpm typecheck`：前端静态检查。
|
||
- `pnpm build`：构建文档站。
|
||
- `pnpm start`：在本地预览已构建站点。
|
||
- `pnpm check`：依次执行 lint、类型检查、制图与构建。
|
||
|
||
站点默认浅色，使用本地系统字体。全站搜索支持正文关键词、`⌘/Ctrl K`、方向键与 Enter；代码块提供复制与反馈。桌面提供分组导航和滚动高亮的页内目录，小屏可展开文档菜单与页内目录。首页入口、草案提示、前后篇导航均引用现有 Markdown 内容。
|
||
|
||
参考设计截图与研究记录保存在 `design/references`；浏览器验收截图与检查说明保存在 `design/verification`。这些文件不作为站点静态资源发布。
|
||
|
||
文档标题取首个 `# 标题`，文档排序按文件名。普通 Markdown 与 GFM 表格可用，嵌入图使用 `/figures/<name>.svg`。不解析原始 HTML。
|
||
|
||
生产构建会生成文档路由；新增或修改文档后重新运行 build。开发模式按请求读取内容。
|
||
main 推送通过 CI 验证后自动部署；Pull Request 只验证，不部署。工作流也支持手动触发。
|
||
|
||
## Endor 概念图
|
||
|
||
`content/docs/00-endor-concepts-draft.md` 解释全球入口、区域网关与 Runtime、分片、CDN、身份及跨区恢复的概念设计，页面为 `/docs/00-endor-concepts-draft`。
|
||
|
||
图形源码位于 `tools/figures/src/endor_figures/architecture.py`，由 `pnpm figures` 生成 `apps/docs/public/figures/endor-architecture.svg`。Python 负责可复现的节点、全连接和复制路径，React 查看器提供放大、滚动与 SVG 下载。无需外部图标、字体或绘图服务。图中的数量是示意，身份服务/CDN 接入属于建议，所有未实现的关系均以草案说明。
|
||
|
||
拓扑检查：`uv run --locked --project tools/figures python -m unittest discover -s tools/figures/tests -v`。容器检查流程会运行同一检查。
|
||
|
||
## CI/CD 与缓存
|
||
|
||
`.gitea/workflows/ci-deploy.yml` 使用已有 ces-control Runner，不修改共享 Runner 配置。
|
||
|
||
1. 对实际构建输入计算 SHA-256：前端源码、Markdown、图片、Python 制图源码、依赖锁文件、Dockerfile 和构建脚本。
|
||
2. 命中 `verified-<scope>-<摘要>` 镜像时跳过依赖安装和 Next.js build，只做实际路由与资源冒烟检查。
|
||
3. 输入变化时运行 lint、类型检查、制图一致性检查与构建。pnpm store、uv 和 `.next/cache` 使用持久 Docker 卷，main 与每个 PR 独立；额外保留 Next.js SWC 下载缓存。
|
||
4. 生产镜像只包含 Next.js standalone 产物；Python 留在检查容器，不进入运行镜像。镜像通过健康、全部文档、JS/CSS、SVG 和 404 检查后才标记为 verified。
|
||
5. 部署前检查是否仍为最新 main，使用 `--no-build` 启动，失败恢复上一版镜像。
|
||
|
||
根 README、工作流或部署配置等非构建输入变化不会触发 Next.js 重建；Markdown 正文变化会更新静态页面，仍需要一次增量构建。首次构建必须安装依赖并完整生成产物。缓存可能因基础镜像、工具链或锁文件变化而失效；不要清理共享 Docker 缓存或卷。
|
||
|
||
默认入口为服务器的 **18135** 端口。容器监听 3000，使用独立 Compose 项目 `endorphin-tabularium-docs`。部署前先检查端口是否空闲（或属于本服务），不会停止其他服务以抢占端口。服务器配置位于 `/etc/endorphin-tabularium-docs/production.env`：
|
||
|
||
```dotenv
|
||
TABULARIUM_BIND=0.0.0.0
|
||
TABULARIUM_PORT=18135
|
||
```
|
||
|
||
发布记录位于 `/opt/endorphin-tabularium-docs/releases/<commit>`，`current` 指向最近成功发布。修改服务器入口配置后手动重跑 main 工作流即可，复用现有镜像。
|
||
|
||
健康检查：`/api/health`。本项目不修改 Hestia、PROMPT 或其他服务，也不自动修改防火墙、域名和反向代理。
|
||
|
||
## Git 远程
|
||
|
||
仓库：[endorphin-tabularium-docs](https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs)。开发者 Git 操作使用 codex-bot 专用 SSH；Actions 检出使用 Gitea 内置任务令牌，不保存检出凭据。
|