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的子命令时会显式跳过manageif 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。下表按用途分组整理默认值均来自当前仓库源码路径类参数决定生成器读写位置参数说明默认值-C, --cwd string设置 git 命令执行的工作目录CWD空-d, --dir.root string仓库根目录./--dir.docs string文档根目录docs--dir.docs.adr stringADR 数据目录相对--dir.docs.contentreference/architecture-decision-log--dir.docs.cli-reference string存放生成 Markdown 的目录reference/cli--dir.docs.content string文档内容目录content--dir.docs.data string文档数据目录data--dir.docs.static string文档静态文件目录static--dir.docs.static.json-schemas stringJSONSchema 静态文件目录schemas--dir.locales stringlocales 目录相对仓库根internal/server/locales--dir.schema string配置 schema 目录相对仓库根internal/configuration/schema--dir.web string前端 web 目录相对仓库根web文件类参数指定具体文件路径参数说明默认值--file.bug-report stringbug report issue 模板文件路径.github/ISSUE_TEMPLATE/bug-report.yml--file.commit-lint-config stringcommit lint JS 配置文件相对仓库根commitlint.config.mjs--file.configuration-keys string配置 keys 文件路径internal/configuration/schema/keys.go--file.docs-commit-msg-guidelines string提交信息规范文档相对仓库根docs/content/contributing/guidelines/commit-message.md--file.docs.data.keys string文档 keys 数据文件路径configkeys.json--file.docs.data.languages string语言数据文件相对 docs data 目录languages.json--file.docs.data.misc string杂项数据文件相对 docs data 目录misc.json--file.docs.static.json-schemas.configuration string配置 JSONSchema 路径configuration--file.docs.static.json-schemas.exports.identifiers stringidentifiers 导出 JSONSchema 路径exports.identifiers--file.docs.static.json-schemas.exports.totp stringTOTP 导出 JSONSchema 路径exports.totp--file.docs.static.json-schemas.exports.webauthn stringWebAuthn 导出 JSONSchema 路径exports.webauthn--file.docs.static.json-schemas.user-database string用户数据库 JSONSchema 路径user-database--file.feature-request stringfeature request issue 模板文件路径.github/ISSUE_TEMPLATE/feature-request.yml--file.scripts.gen stringauthelia-scripts 的 gen 文件路径cmd/authelia-scripts/cmd/gen.go--file.server.generated stringserver 生成文件路径internal/server/gen.go--file.web.i18n stringi18n TypeScript 配置相对 web 目录src/i18n/index.ts--file.web.package stringNode 包配置相对 web 目录package.json包名与行为类参数参数说明默认值--package.configuration.keys stringkeys 文件的包名schema--package.scripts.gen stringauthelia-scripts gen 文件的包名cmd--latest启用 latest 功能如 JSON Schema 生成器false--next启用 next 功能如 JSON Schema 生成器false--version-count int输出模板中列出的最大 minor 版本数5--versions strings指定生成器运行的版本特殊值current与next互斥空-X, --exclude strings设置要排除的生成器名称空上述默认常量均定义于 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 adrdocs 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参数说明对应模板字段--title string记录标题Title--status string记录状态Status--context string记录背景/上下文Context--proposed-design string提议的设计方案ProposedDesign--decision string最终决策Decision--consequences string决策带来的影响Consequences--related-adrs ints相关联的 ADR 编号可多个RelatedADRs完整调用示例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 的实现通过getPFlagPath将--dir.docs、--dir.docs.content、--dir.docs.adr拼接为完整 ADR 目录见 helpers.gofilepath.Join逐级拼接读取该目录下的.adr.config.json配置文件并解析出next_id计算新记录数据ADR 编号取next_idweight为1000 next_id保证新 ADR 在文档站排序中靠后日期自动取当前时间校验--related-adrs中的每个编号必须小于next_id否则报错related adr %d does not exist yet将数据灌入模板生成{adrs}/{编号}.md文件将配置中的next_id自增 1 并回写.adr.config.json执行git add将新 ADR 文件加入暂存区。ADR 配置与模板机制配置文件ADR 目录下的.adr.config.json维护next_id见ArchitectureDesignRecordConfig是编号分配与自增的唯一数据源文档模板docs-architectural_design_record.md.tmpl见 cmd/authelia-gen/templates定义输出格式包含 front mattertitle、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-logADR 文档实际存放位置即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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
