你的基础设施，自动生成文档。

InfraJournal 读取你已经在维护的配置文件——Docker Compose、Nginx 和 Caddy——并将它们转化为一份稳定的基础设施清单：服务、网络、卷、域名、端点、依赖关系、警告以及架构决策记录。扫描以本地优先、确定且只读的方式进行；init、generate 和 scan --output 仅在明确要求时才写入文件。扫描不需要 Docker daemon、云凭证或网络访问。

当前版本：0.1.3。如果你安装的是 0.1.0，请升级：该版本的 npm 可执行文件会直接退出而不执行任何操作。0.1.1 修复了全局安装和 npx 调用的问题；0.1.3 修复了 init 生成的配置，包括使用 docker-compose.yml 的项目。

基础设施知识散落在 Compose 文件、代理配置、备份笔记以及某个人脑子里的决策中。架构图会过时，新人上手需要好几天，而且没人确定哪个服务实际上是对外公开的。

InfraJournal 从这些文件构建文档，而不是要求你维护第二份副本。解析出的事实带有来源位置和证据，因此你能看到某个内容为何出现在清单中。推断出的关联会被标注为推断。缺失的备份策略会作为发现项报告，而不是被默默假定为存在。

从 npm 安装（需要 Node.js 22.12 或更高版本）： npm install --global infrajournal infrajournal --version

或无需全局安装直接运行：

npx infrajournal --help

从源码构建（需要 pnpm 12）： git clone https://github.com/AkemiFF/infrajournal.git cd infrajournal corepack enable pnpm install --frozen-lockfile pnpm build node packages/cli/dist/index.js --version

以下示例使用已安装的 infrajournal 命令。在仅含源码的检出中，请用 node packages/cli/dist/index.js 替代。

多服务示例是一个贴近真实场景的技术栈：Nginx 位于 Web 应用和 worker 之前，PostgreSQL、Redis、三个命名卷和三个 ADR。其中不包含可运行的密钥。

从仓库根目录执行；--root 加载示例的 infrajournal.yml。

infrajournal scan --root examples/multi-service infrajournal generate --root examples/multi-service infrajournal check --root examples/multi-service infrajournal ui --root examples/multi-service

generate 会写入 examples/multi-service/infra-docs/（该目录被 Git 忽略）。打开 ui 打印的 URL，按 Ctrl+C 停止服务器。对于你自己的技术栈，在其目录中运行 infrajournal init 并按照入门指南操作。

扫描会报告它发现的服务和路由，并标记已发布的 Nginx 端口以及 uploads 卷未记录的备份策略。pgdata 和 redisdata 的备份策略在该示例的 infrajournal.yml 中有记录；警告并不意味着备份缺失。扫描是只读的。

有关 npm 和源码两种工作流，请参阅入门指南。

扫描与汇总

在 stdout 输出人类可读的摘要。

infrajournal scan

仅在 stdout 输出机器可读的快照（无横幅或日志）。

infrajournal scan --format json | jq '.stats'

JSON 包含 schemaVersion、project、资源数组、warnings、stats 和 metadata 字段；stats 包含本次扫描的计数，而非固定的示例指标。将其管道传给 jq '.stats' 即可查看。

scan --format json 输出 docs/architecture.md 中描述的快照对象。除非指定 --output <file>，否则它绝不写入文件。

infrajournal generate

在 output.directory（默认 ./infra-docs）下写入 Markdown 和 snapshot.json。生成的文件带有标记；没有标记的文件会被保留，因此手写笔记不会被覆盖。确切的生成文件列表记录在 docs/configuration.md 中。

infrajournal check

无漂移时，命令退出码为 0。如果当前扫描与基线不同，它会报告新增、删除和变更的资源，并以退出码 3 退出。基线缺失时退出码为 4；配置/用法错误退出码为 2；意外的运行时故障退出码为 1。check 绝不重写基线。

编辑受支持的配置后，在刷新基线之前先检查漂移。

infrajournal check --format json > drift.json

漂移时返回 3，因此不要在未处理该退出码的情况下直接管道传给另一个命令。查看 drift.json，然后根据需要运行 generate。

启动本地仪表盘

infrajournal ui # 扫描，并在 http://127.0.0.1:4173/ 提供服务 infrajournal ui --port 8080

服务器仅绑定到 127.0.0.1。如果默认端口被占用，它会尝试接下来的 20 个端口并打印所选 URL；显式指定但被占用的端口则视为错误。npm 包包含仪表盘；仅在从源码运行时才需要 pnpm build。

本地仪表盘将可搜索的架构图与来源证据、相关警告和服务详情结合在一起：

这是从捆绑示例生成的真实截图。运行 infrajournal ui --root examples/multi-service 即可在本地探索；仪表盘绑定到 localhost，不会联系远程服务。

输入 默认检测 支持的子集 Docker Compose compose.yml、compose.yaml、docker-compose.yml、docker-compose.yaml 单文件 Compose 的 services、ports、volumes、networks、depends_on、healthcheck、restart、environment 键、env_file 路径、labels Nginx /nginx/*.conf、/nginx/**/.conf server、字面量 server_name、location、字面量 proxy_pass、upstream、TLS 存在性 Caddy Caddyfile、Caddyfile. 站点地址、reverse_proxy、基本路径匹配器、handle/handle_path、TLS 存在性 决策 decisions.directory 下的 *.yml / *.yaml id、title、status、date、context、decision、consequences、related_services

如果你的文件使用其他位置，请在 scan.include 中添加路径。包含模式和排除语义记录在 docs/configuration.md 中。子集之外的任何内容，在解析器能够识别的情况下会作为警告报告，否则会被忽略。

领域 限制 Compose 不支持插值、变量解析、多文件合并、include、extends 解析、profiles、configs 或 secrets 内容。 Compose

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）