全栈开发 / AI 内容工程

AI 工程技术博客与内容交付平台

以 GitHub Markdown 为权威内容源，使用 Astro、Fastify、PostgreSQL、Pagefind 和版本化 Docker 镜像完成研究归档、静态发布、读者交互与受控部署。

2026-06 - 至今当前代码
  • Astro
  • TypeScript
  • Fastify
  • PostgreSQL
  • Markdown
  • Pagefind
  • Docker

Reuse contract

复用合同

真实运行已验证JSON 清单
最近核验
2026/07/19
固定版本
83952b3bae58
代码入口
project-kits/ai-blog-portfolio/README.md公开副本固定源码

输入

  • src/content/posts 与 src/content/projects 中通过 schema 的 Markdown 内容
  • 历史来源账本、冻结实验结果和 Asia/Shanghai 发布日合同
  • 构建期站点配置与服务器运行期的最小权限环境变量

输出

  • Astro 静态 HTML、RSS、Sitemap、Pagefind 索引与内容清单
  • 包含 dist 和 Fastify build-server 的固定版本 Docker 镜像
  • 部署、readiness、告警、备份与恢复的可审计运行记录

可执行命令

editorial-check测试
npm run editorial:check
平台
macOS、Linux 或 Windows；离线 Node.js
权威输出
stdout 中的文章、历史研究和负例数量；退出码 0 表示编辑合同通过
副作用
不修改状态
前置条件
  • Node.js >=22.12.0
  • 仓库根目录与完整文章来源账本
content-contract测试
npm run content:contract
平台
macOS、Linux 或 Windows；离线 Node.js
权威输出
stdout 中的 CMS/内容合同一致性结论；退出码 0 为通过
副作用
不修改状态
前置条件
  • Node.js >=22.12.0
  • 仓库根目录中的 Astro 与 CMS schema
deployment-contract-test测试
npm run deploy:test
平台
macOS 或 Linux；使用隔离的 mock Docker/HTTP fixture
权威输出
stdout 中的部署、验签、备份、readiness 和回滚合同结论
副作用
会修改运行环境
前置条件
  • Node.js >=22.12.0
  • POSIX shell 与可写系统临时目录
monitoring-contract-test测试
npm run monitor:test
平台
macOS 或 Linux；使用隔离的监控 fixture
权威输出
stdout 中的七项运行检查、告警转换、留存与恢复证据结论
副作用
会修改运行环境
前置条件
  • Node.js >=22.12.0
  • POSIX shell 与可写系统临时目录

可直接复用

  • 复用内容 collection、日期门禁和来源合同搭建证据型技术站点
  • 复用 GitHub -> CI -> GHCR -> 宿主机 agent 的受控发布链路
  • 复用评论、账户、管理员 MFA、监控和回滚边界构建小型内容产品

明确边界

  • 公开文章会被编译进发布镜像，但 GitHub Markdown 仍是权威源；运行时不能直接编辑镜像内正文。
  • 生产证据覆盖单实例发布、一次真实维护恢复和固定日期的告警演练，不代表高流量或多节点可用性。
  • 自动门禁只能验证结构和已编码合同，不能替代作者逐条核对事实、来源与引用语境。

固定结果工件

  • 生产监控与恢复证据monitoring-production-evidence
    仓库路径
    docs/monitoring-production-evidence.md
    SHA-256
    46cd4d241b368d097d7b7067abcebbec912bbddd8f6bb6f5dbf6784c3e070b3a
    生成/验证命令
    monitoring-contract-test
    公开副本固定源码
  • v0.1.10 生产告警与恢复验收release-v010-production-evidence
    仓库路径
    docs/release-v0.1.10-production-evidence.md
    SHA-256
    ef0df95f0a5a05cd26d94431f877db3a0a29ef145faad575c3daaa4b44068f7d
    生成/验证命令
    deployment-contract-test
    公开副本固定源码

问题与目标

项目解决的不是“如何生成一个博客页面”，而是如何让研究、实验、项目、时间线和部署证据共享同一套可追溯内容合同。文章需要能被读者访问，也需要保留来源、日期、结果工件和修订边界；发布系统则必须保证草稿、凭据和生产控制面不会因为静态站点公开而一起暴露。

当前目标包括：让文章和项目从 Git 中可审查地演进，让构建结果可重复，让生产部署只接受固定版本，让账户、评论和部署状态与文章正文分开存储，并让编辑与工程门禁在发布前给出明确失败原因。

内容、镜像与数据库怎样分工

文章权威源位于 src/content/posts/，项目权威源位于 src/content/projects/。它们随代码提交进入 GitHub，而不是由生产数据库临时生成。Astro 构建时读取当前 commit 的 Markdown，将公开内容编译为 HTML、RSS、Sitemap、搜索索引和内容清单。

Docker 多阶段构建随后只把 dist/、编译后的 Fastify 服务和数据库 migration 放入 runtime 镜像。文章因此会出现在镜像的静态发布产物里，但那是一个固定 commit 的发布快照，不是新的数据仓库。正文要更新时仍应修改 GitHub 中的 Markdown、通过门禁、构建新镜像并重新部署；不在服务器容器内直接改 HTML。

PostgreSQL 保存用户、会话、评论、访问统计、MFA、部署任务和审计等运行状态，不保存文章的权威正文。把三者分开后，Git 负责内容版本，镜像负责可回滚交付，数据库负责需要在线变化的业务状态。

可复用交付链路

内容 collection 在构建前校验 frontmatter；编辑检查进一步验证来源、历史 T+2 边界、文件名与日期合同。npm run preflight 还覆盖 Node 版本、安全扫描、时间线、实验、服务端、认证、部署、备份恢复、签名、监控、CMS、防护、生产构建与静态 smoke。

通过门禁的 tag workflow 构建私有 GHCR 镜像。服务器只持有 read:packages 所需凭据，宿主机 agent 拉取指定 SemVer 版本并执行 readiness 检查；应用容器不挂载 Docker socket。失败版本由部署脚本回滚，生产 /admin/* 与本地写作入口分离。

当前证据

截至本次核验，仓库有 65 篇公开文章和 37 个已核验事件节点。这些数量由内容清单和时间线验证脚本读取真实文件得出，不再沿用旧项目页中的 42/27。

docs/monitoring-production-evidence.md 记录了生产环境的四步 HTTPS 告警演练、最小权限状态文件、数据库备份、容器 logging driver 切换，以及一次 split-compose 误删服务后的真实恢复。它支持本项目发布与运维链路的 field-tested 等级，但不证明读者增长、所有业务功能或多节点高可用。

使用边界

公开静态正文无法对访问者保密；安全目标是保护草稿、私有源码、GitHub 凭据、数据库秘密和部署控制面。当前发布仍是单实例更新，短请求可能在切换时出现数秒中断，高流量前需要升级为蓝绿或等价策略。

复用本项目时，应先保留 Git 内容源、构建产物和运行数据库的边界，再按实际需求裁剪账户或 CMS。不要把生产数据库当文章仓库，也不要把镜像中的 HTML 反向当成可编辑源文件。

Research links

关联文章

这些文章分别提供问题背景、设计依据、实验验证或运行证据。

  1. 发布 2026/06/24

    本文把模型、RAG、Agent、Prompt、工程化和项目表达组织为文章理解与项目证据两类材料，为本站用文章反查可执行项目、用项目回指方法与证据提供作品集语境。

  2. 发布 2026/06/25

    本文给出问题、目标、架构、结果与复盘骨架，本站项目页沿用这套结构组织可核验交付证据。

  3. 发布 2026/06/26

    本文描述选题、整理、Markdown 落库与发布检查的通用内容流程，为本项目从 Git 内容源到构建门禁提供工作流背景。

  4. 发布 2026/07/01

    本文提出固定样本、失败归因与上线门槛，本项目据此设计文章实验工件和 preflight 检查，但它本身不是项目运行证据。