来源：2026-07-07 个人网站项目会话
这篇文章由本地 Codex 历史会话整理而来，保留可复用的工程经验，省略私有路径、账号、临时日志和不适合公开发布的细节。
项目的真实边界
这个个人网站的结构有一个容易被忽略的特点：根目录不是 Git 仓库，docs/ 才是独立的发布仓库。运行态后端在 1.py，静态构建在 build.py，公开站点由 docs/ 输出。理解这个边界，是避免误改生成物、误提交源码或把本地后端当公网服务的前提。
因此发布链路不是“随便改 HTML 然后 push”，而是：改根目录模板或数据，运行 python build.py 生成 docs/，本地 HTTP 预览，再只提交 docs/ 中的发布结果。
本次链路里沉淀的几个规则
第一，前后端一键启动要尊重端口边界。后端默认 8000，静态前端默认 8001；端口冲突时脚本自动顺延，避免两个服务抢同一个端口。
第二，公开页面视觉优先收敛到 site.css，不要在多个模板里重复大段样式。模块卡片等高也是在公共样式层完成，并用浏览器实际测量卡片高度验证。
第三，后端管理体验可以优化，但不必引入框架。当前项目是本地单文件后端，标准库足够支撑健康检查、JSON 响应和管理页筛选；引入 Flask/FastAPI/Django 会扩大迁移面。
发布前检查清单
运行 python -m py_compile 1.py build.py，确认脚本语法没有破坏。
运行 python build.py，确认文章页、模块页、docs/data/*.json 和上传资源能重新生成。
用本地 HTTP 服务预览 docs/，不要只用 file://，因为站点中存在 /site.css 和 /uploads/... 这类绝对路径。
进入 docs/ 仓库查看 git status 和 git diff --stat，确认要推送的是发布结果，而不是临时文件。
沉淀
对个人网站来说，稳定的发布链路比一次性的页面美化更重要。只要构建、预览、验证、提交、推送能稳定重复，后续每次新增文章或调整样式都会轻很多。