Deploy Tabularium on ces-control with verified image reuse and persistent caches

README.md

@@ -1,11 +1,11 @@
 # Endor · Tabularium
 
-Endor 文档与制图 monorepo。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
@@ -33,9 +33,31 @@ tools/figures/  独立 Python 项目，使用 drawsvg 编程制图
 文档标题取首个 `# 标题`，文档排序按文件名。普通 Markdown 与 GFM 表格可用，嵌入图使用 `/figures/<name>.svg`。不解析原始 HTML。
 
 生产构建会生成文档路由；新增或修改文档后重新运行 build。开发模式按请求读取内容。
-所有工作流只在本地执行，不配置 CI 或部署。远程 Git 仅用于保存和同步源码。
+main 推送通过 CI 验证后自动部署；Pull Request 只验证，不部署。工作流也支持手动触发。
+
+## 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 独立。
+4. 生产镜像只包含 Next.js standalone 产物；Python 留在检查容器，不进入运行镜像。镜像通过健康、全部文档、JS/CSS、SVG 和 404 检查后才标记为 verified。
+5. 部署前检查是否仍为最新 main，使用 `--no-build` 启动，失败恢复上一版镜像。
+
+README 或工作流等非构建输入变化不会触发 Next.js 重建；Markdown 正文变化会更新静态页面，仍需要一次增量构建。首次构建必须安装依赖并完整生成产物。缓存可能因基础镜像、工具链或锁文件变化而失效；不要清理共享 Docker 缓存或卷。
+
+默认入口为服务器的 **18132** 端口。容器监听 3000，使用独立 Compose 项目 `endorphin-tabularium-docs`。服务器配置位于 `/etc/endorphin-tabularium-docs/production.env`：
+
+```dotenv
+TABULARIUM_BIND=0.0.0.0
+TABULARIUM_PORT=18132
+```
+
+发布记录位于 `/opt/endorphin-tabularium-docs/releases/<commit>`，`current` 指向最近成功发布。修改服务器入口配置后手动重跑 main 工作流即可，复用现有镜像。
+
+健康检查：`/api/health`。本项目不修改 Hestia、PROMPT 或其他服务，也不自动修改防火墙、域名和反向代理。
 
 ## Git 远程
 
-请创建空仓库 `endorphin-tabularium-docs`，不要初始化 README 或许可证。
-得到实际仓库地址后再添加 origin 并推送。不要假定仓库所有者或使用其他用户凭据。
+仓库：[endorphin-tabularium-docs](https://gitea.entroia.com/Zayden-Jung/endorphin-tabularium-docs)。开发者 Git 操作使用 codex-bot 专用 SSH；Actions 检出使用 Gitea 内置任务令牌，不保存检出凭据。