企业官网建设流程全解析

authelia-gen docs manage 命令详解：Authelia 文档生成器的受管文档与架构决策记录（ADR）工具链

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia

导读

本文围绕 Authelia 官方文档生成器authelia-gen的docs manage命令展开，深入讲解其作为"受管文档（Managed docs）"生成入口的定位、命令层级结构与全部继承参数，并结合仓库源码剖析其唯一子命令docs manage adr（架构决策记录生成）的完整工作流程、文件模板与配置机制。读完本文，你将掌握如何通过authelia-gen docs manage adr add为 Authelia 文档站生成符合规范的 ADR 文档，以及每个命令参数在源码中的实际作用，可直接用于 Authelia 项目的文档维护与二次开发。

authelia-gen是 Authelia 仓库内置的代码与文档生成工具链，其 CLI 定义位于 cmd/authelia-gen 目录，基于 spf13/cobra 构建。本文对应的官方参考文档为 authelia-gen_docs_manage.md。

命令定位：什么是 "Managed docs"

在 cmd_docs.go 中，docs父命令共注册了六个子命令：cli、data、date、seo、json-schema与manage。其中manage使用cmdUseManage = "manage"（见 const.go），其命令简介为 "Generate Managed docs"，即"生成受管文档"。

所谓"受管文档"，从源码结构看，指的是那些不是直接手写、而是由生成器依据模板与配置文件自动产出并纳入版本管理的文档。当前manage下挂载的唯一子命令是adr（架构决策记录），说明本仓库中"受管文档"的具体落地形态即为 ADR 文档——每次新增 ADR 时，命令会自动生成带固定 front matter、自增编号与时间戳的 Markdown 文件，并更新 ADR 配置文件、执行git add，实现文档全流程的自动化管理。

// cmd/authelia-gen/cmd_docs.go func newDocsManageCmd() *cobra.Command { cmd := &cobra.Command{ Use: cmdUseManage, Short: "Generate Managed docs", DisableAutoGenTag: true, } cmd.AddCommand(newADRCmd()) return cmd }

一个值得注意的细节：在 cmd_root.go 的rootSubCommandsRunE中，当批量执行docs的子命令时会显式跳过manage：

if cmd.Use == cmdUseDocs && subCmd.Use == cmdUseManage { continue }

这意味着authelia-gen docs（不带子命令）的批量执行不会包含manage分支，docs manage必须作为独立命令显式调用，这与"ADR 需要人工交互填写内容"的特性相符。

命令语法与自身选项

authelia-gen docs manage本身不接收任何业务参数，仅提供标准的帮助选项：

-h, --help help for manage

查看完整帮助信息：

authelia-gen docs manage --help

从父命令继承的全局参数

docs manage可继承authelia-gen根命令（见 cmd_root.go）定义的全部持久化标志（Persistent Flags）。下表按用途分组整理，默认值均来自当前仓库源码：

路径类参数（决定生成器读写位置）

文件类参数（指定具体文件路径）

包名与行为类参数

上述默认常量均定义于 const.go，例如dirDocsADR = "reference/architecture-decision-log"、fileCodeConfigKeys = "internal/configuration/schema/keys.go"等。需要注意：这些参数中与 ADR 直接相关的是--dir.docs、--dir.docs.content与--dir.docs.adr三个，它们共同决定 ADR 文件的落盘目录。

核心子命令：docs manage adr

docs manage adr简介为 "Generate an Architecture Decision Record"，官方参考文档见 authelia-gen_docs_manage_adr.md。其实现位于 cmd_adr.go，结构为：

func newADRCmd() *cobra.Command { cmd := &cobra.Command{ Use: "adr", Short: "Generate an Architecture Decision Record", DisableAutoGenTag: true, } cmd.AddCommand(newADRAddCmd()) return cmd }

adr自身同样仅有-h, --help选项，真正执行逻辑的是其子命令adr add。

实操：生成一份 ADR 记录

命令语法

authelia-gen docs manage adr add [flags]

专属选项

adr add定义了 7 个业务参数，全部可选（cmd_adr.go）：

完整调用示例

authelia-gen docs manage adr add \ --title "Adopt Post-Quantum Signature Algorithms for OIDC" \ --status "Proposed" \ --context "OIDC 令牌签名需要抵御量子计算攻击" \ --proposed-design "引入基于 ML-DSA 的签名算法支持" \ --decision "在 OIDC 签名策略中增加 ML-DSA 选项" \ --consequences "客户端需同步升级以支持新算法" \ --related-adrs 1,2

执行后，命令会依次完成以下工作（对应 adrAddRunE 的实现）：

1. 通过getPFlagPath将--dir.docs、--dir.docs.content、--dir.docs.adr拼接为完整 ADR 目录（见 helpers.go，filepath.Join逐级拼接）；
2. 读取该目录下的.adr.config.json配置文件并解析出next_id；
3. 计算新记录数据：ADR 编号取next_id，weight为1000 + next_id（保证新 ADR 在文档站排序中靠后），日期自动取当前时间；
4. 校验--related-adrs中的每个编号必须小于next_id，否则报错related adr %d does not exist yet；
5. 将数据灌入模板生成{adrs}/{编号}.md文件；
6. 将配置中的next_id自增 1 并回写.adr.config.json；
7. 执行git add将新 ADR 文件加入暂存区。

ADR 配置与模板机制

• 配置文件：ADR 目录下的.adr.config.json维护next_id（见ArchitectureDesignRecordConfig），是编号分配与自增的唯一数据源；
• 文档模板：docs-architectural_design_record.md.tmpl（见 cmd/authelia-gen/templates）定义输出格式，包含 front matter（title、date、weight、toc、seo）、Date、Status、Submitters、Change Log、Context、Proposed Design、Decision、Consequences、Related ADRs等小节。其中Status、Context、Proposed Design、Decision、Consequences未提供时渲染为Proposed/_N/A_等默认值；
• 模板加载：templates.go 通过//go:embed templates/*将模板内嵌进二进制，tmplADR注册了joinX等辅助函数（templates.FuncMap()），生成时无需外部模板文件。

从 templates.go 可确认：docs/architecture-decision-log（ADR 文档实际存放位置，即docs/content/reference/architecture-decision-log）内的文档正是由该模板渲染而来。

命令层级总览与 SEE ALSO 导航

docs manage的完整命令树如下：

authelia-gen └── docs ├── cli / data / date / seo / json-schema # 其他文档生成器 └── manage ├── adr │ └── add └── (help)

官方参考文档的 SEE ALSO 部分提供了相邻文档入口（均已转换为仓库根相对路径）：

• 父命令：authelia-gen docs —— "Generate docs"
• 兄弟子命令：authelia-gen docs manage adr —— "Generate an Architecture Decision Record"
• 深层子命令：authelia-gen docs manage adr add —— "Add an Architecture Decision Record"

常见问题与使用要点

• 为什么docs manage不含在批量执行中？从 cmd_root.go 可见，根命令遍历子命令批量运行时显式continue跳过了manage，因此 ADR 生成必须显式指定完整命令链authelia-gen docs manage adr add。
• ADR 编号如何分配？编号来自.adr.config.json的next_id，每次成功生成后自增；weight与编号联动（1000 + next_id），保证文档站按权重顺序展示。
• 能否跳过 git add？当前实现中git add是固定步骤（cmd_adr.go），无法通过参数关闭；如需控制可结合--cwd指定 git 仓库位置。
• 多版本文档生成：--versions、--latest、--next主要用于 JSON Schema 等多版本生成器，对manage adr不产生实际影响。

结语

authelia-gen docs manage是 Authelia 文档工具链中面向"受管文档"的命令入口，当前承载着架构决策记录（ADR）的自动化生成职责。通过adr add的 7 个参数与.adr.config.json的编号机制，维护者可以标准化、可追溯地沉淀每次架构决策；其"模板渲染 + 编号自增 + 自动 git add"的实现思路（详见 cmd_adr.go），也为在 Authelia 体系中扩展其他受管文档类型提供了可参考的范式。

【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/authelia