Authelia 架构决策记录生成器authelia-gen docs manage adr 命令完整指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 是开源的单点登录SSO与多因素认证MFA门户其文档体系庞大且高度工程化。为了维护文档中架构决策日志ADL这类半正式记录的一致性与规范性Authelia 提供了authelia-gen生成器工具链而本文聚焦其中的authelia-gen docs manage adr命令它负责生成、新增一份符合官方模板的架构决策记录ADR。读完本文你将掌握该命令的完整选项、它与adr add子命令的分工、底层实现如何自动编号并调用git add以及一份合法 ADR 文档应有的章节结构。命令概览作用与定位authelia-gen docs manage adr是authelia-gen工具链中用于生成架构决策记录的命令。在命令层级上它处于如下位置可对照 cmd_docs.go 中newDocsCmd与newDocsManageCmd的注册逻辑authelia-gen └── docs # Generate docs └── manage # Generate Managed docs └── adr # Generate an Architecture Decision Record └── add # Add an Architecture Decision Record从源码看cmd_docs.go 中newDocsManageCmd通过cmd.AddCommand(newADRCmd())挂载了adr子命令而 cmd_adr.go 中newADRCmd又挂载了add子命令。也就是说authelia-gen docs manage adr本身是一个命令分组namespace真正的写盘动作由其子命令add完成分组命令本身只提供-h, --help帮助选项不执行任何文件写入逻辑。该命令的官方描述为Generate an Architecture Decision Record生成一份架构决策记录对应参考文档位于 authelia-gen_docs_manage_adr.md。命令选项解析authelia-gen docs manage adr自身不接收业务参数仅提供帮助选项-h, --help help for adr真正的参数全部集中在其子命令authelia-gen docs manage adr add上详见 authelia-gen_docs_manage_adr_add.md。该子命令支持以下选项选项类型说明--title stringstring设置记录的标题--status stringstring设置记录的状态--context stringstring设置记录的上下文背景--proposed-design stringstring设置记录的拟议设计--decision stringstring设置记录作出的决策--consequences stringstring设置记录带来的后果--related-adrs intsint slice设置与本记录相关的其他 ADR 编号-h, --help-帮助这些选项与 cmd_adr.go 中cmd.Flags()的注册一一对应可直接通过cmd.Flags().GetString(...)/GetIntSlice(...)读取。继承自父命令的全局选项与authelia-gen的其他命令一样docs manage adr会继承父命令定义的全部全局选项。这些选项主要控制目录定位、文件路径与生成行为是理解该命令在哪里读写文件的关键-C, --cwd string Sets the CWD for git commands --dir.authentication string The authentication directory in relation to the root (default internal/authentication) --dir.docs string The directory with the docs (default docs) --dir.docs.adr string The directory with the ADR data (default reference/architecture-decision-log) --dir.docs.cli-reference string The directory to store the markdown in (default reference/cli) --dir.docs.content string The directory with the docs content (default content) --dir.docs.data string The directory with the docs data (default data) --dir.docs.static string The directory with the docs static files (default static) --dir.docs.static.json-schemas string The directory with the docs static JSONSchema files (default schemas) --dir.locales string The locales directory in relation to the root (default internal/server/locales) -d, --dir.root string The repository root (default ./) --dir.schema string The schema directory in relation to the root (default internal/configuration/schema) --dir.web string The repository web directory in relation to the root directory (default web) -X, --exclude strings Sets the names of excluded generators --file.bug-report string Sets the path of the bug report issue template file (default .github/ISSUE_TEMPLATE/bug-report.yml) --file.commit-lint-config string The commit lint javascript configuration file in relation to the root (default commitlint.config.mjs) --file.configuration-keys string Sets the path of the keys file (default internal/configuration/schema/keys.go) --file.docs-commit-msg-guidelines string The commit message guidelines documentation file in relation to the root (default docs/content/contributing/guidelines/commit-message.md) --file.docs.data.keys string Sets the path of the docs keys file (default configkeys.json) --file.docs.data.languages string The languages docs data file in relation to the docs data folder (default languages.json) --file.docs.data.misc string The misc docs data file in relation to the docs data folder (default misc.json) --file.docs.static.json-schemas.configuration string Sets the path of the configuration JSONSchema (default configuration) --file.docs.static.json-schemas.exports.identifiers string Sets the path of the identifiers export JSONSchema (default exports.identifiers) --file.docs.static.json-schemas.exports.totp string Sets the path of the TOTP export JSONSchema (default exports.totp) --file.docs.static.json-schemas.exports.webauthn string Sets the path of the WebAuthn export JSONSchema (default exports.webauthn) --file.docs.static.json-schemas.user-database string Sets the path of the user database JSONSchema (default user-database) --file.feature-request string Sets the path of the feature request issue template file (default .github/ISSUE_TEMPLATE/feature-request.yml) --file.scripts.gen string Sets the path of the authelia-scripts gen file (default cmd/authelia-scripts/cmd/gen.go) --file.server.generated string Sets the path of the server generated file (default internal/server/gen.go) --file.web.i18n string The i18n typescript configuration file in relation to the web directory (default src/i18n/index.ts) --file.web.package string The node package configuration file in relation to the web directory (default package.json) --latest Enables latest functionality with several generators like the JSON Schema generator --next Enables next functionality with several generators like the JSON Schema generator --package.configuration.keys string Sets the package name of the keys file (default schema) --package.scripts.gen string Sets the package name of the authelia-scripts gen file (default cmd) --version-count int the maximum number of minor versions to list in output templates (default 5) --versions strings The versions to run the generator for, the special versions current and next are mutually exclusive其中与本命令最相关的是--dir.docs.adrADR 数据目录默认reference/architecture-decision-log。该默认值在 const.go 中定义为dirDocsADR reference/architecture-decision-log而 ADR 文档实际存放位置为 docs/content/reference/architecture-decision-log/两者配合使用--dir.docs默认为docs--dir.docs.content默认为content最终由getPFlagPath拼接出完整路径。从源码看 ADR 的生成流程authelia-gen docs manage adr add的核心逻辑实现在 cmd_adr.go 的adrAddRunE函数中整个流程清晰且自动化定位 ADR 目录通过getPFlagPath(cmd.Flags(), cmdFlagRoot, cmdFlagDocs, cmdFlagDocsContent, cmdFlagDocsADR)拼出 ADR 所在目录读取配置读取该目录下的.adr.config.json配置文件反序列化为ArchitectureDesignRecordConfig结构体仅含next_id字段见 cmd_adr.go。注意该文件是命令运行时维护的本地状态文件不在仓库内提交组装模板数据构建ArchitectureDesignRecordTmpl见 cmd_adr.go其中ADR取配置中的NextIDWeight计算为1000 NextID与 Hugo 文档站点的权重机制对齐现有 ADR 如1.md的 weight 为 1001可相互印证日期自动取当前时间分别格式化出 YAML 时间戳、ISO 日期和人类可读日期校验关联 ADR遍历--related-adrs传入的编号若任一编号 config.NextID则直接报错related adr %d does not exist yet防止引用尚不存在的记录写入文件以NextID.md命名创建文件例如第 3 条记录生成3.md执行tmplADR模板渲染递增并回写配置config.NextID 1后以 0600 权限截断重写.adr.config.json保证下一个 ADR 编号连续自动 git 暂存最后执行git add 新文件cmd_adr.go新生成的 ADR 会被直接加入暂存区方便随 MR 一起提交。// cmd/authelia-gen/cmd_adr.go节选 data : ArchitectureDesignRecordTmpl{ ADR: config.NextID, Weight: 1000 config.NextID, Date: time.Now().Format(dateFmtYAML), DateISO: time.Now().Format(time.DateOnly), DateHuman: time.Now().Format(January 2, 2006), }ADR 文档的模板结构新生成的 ADR 并非空白文件而是由模板 docs-architectural_design_record.md.tmpl 渲染而成。该模板定义了 ADR 的完整骨架既包含 Hugo 前端元数据title、description、date、weight、toc、seo也包含 ADR 正文的标准章节Date记录发布日期人类可读格式Status记录状态未提供时默认ProposedSubmitters提交者姓名、链接与所属组织模板中为占位符需要人工填写Change Log变更日志表格含日期、PR、状态、备注四列首次发布时状态默认ProposedContext为什么需要这份 ADR 及其背景未提供时显示_N/A_Proposed Design拟议的设计方案未提供时显示_N/A_Decision最终作出的决策未提供时显示_N/A_Consequences该决策可能带来的不良后果未提供时显示_N/A_Related ADRs相关 ADR 列表模板按传入编号生成指向N.md的链接无相关记录时显示_N/A_。模板中引用的章节正是 introduction.md 中定义的 ADR 关键区块表Status、Context、Proposed Design、Decision、Consequences、Related ADRs。二者相互印证构成 Authelia 架构决策记录的标准格式。实操示例新增一条 ADR结合上文一条完整的实操命令如下假设在仓库根目录执行authelia-gen docs manage adr add \ --title Example: Replace Backing Authentication Service \ --status Proposed \ --context This record describes the context for an example decision. \ --proposed-design A description of the proposed design. \ --decision A description of the decision made. \ --consequences A description of the consequences. \ --related-adrs 1执行后工具会在docs/content/reference/architecture-decision-log/目录下生成形如4.md的文件编号取决于.adr.config.json中的next_id自动填充日期、weight、状态与各章节并通过git add完成暂存。若--related-adrs引用了尚未存在的编号如当前最大编号为 3 却引用 5命令会立即报错终止。与现有 ADR 的对应关系仓库中已提交的 ADR 正是上述模板的产物可作为格式参考ADR1: OpenID Connect Client Authorization Policies展示了完整的 StatusAccepted、Submitters、Change Log、Context、Proposed Design、Decision、Consequences 章节其 front matter 中weight: 1001与源码1000 NextID的计算规则完全吻合目录索引见 architecture-decision-log/_index.md其层级说明见 introduction.md。SEE ALSO命令导航authelia-gen docs manage adr在参考文档中与以下命令互为导航对应 authelia-gen_docs_manage_adr.md 的 SEE ALSO 段落authelia-gen docs manage父命令Generate Managed docsauthelia-gen docs manage adr add子命令Add an Architecture Decision Record。需要理解整个authelia-gen工具链时可从 authelia-gen.md 与 docs 命令组 入手继续阅读。小结authelia-gen docs manage adr是 Authelia 将架构决策纳入工程化文档体系的重要一环它以固定模板统一 ADR 的章节结构以.adr.config.json维护记录编号以git add衔接版本控制流程。对维护者而言这意味着新增一条架构决策记录只需一条命令加若干参数对读者而言所有 ADR 都遵循一致的 Status / Context / Proposed Design / Decision / Consequences 结构便于检索、引用与追溯。结合 cmd_adr.go 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Authelia 架构决策记录生成器：authelia-gen docs manage adr 命令完整指南
Authelia 架构决策记录生成器authelia-gen docs manage adr 命令完整指南【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 是开源的单点登录SSO与多因素认证MFA门户其文档体系庞大且高度工程化。为了维护文档中架构决策日志ADL这类半正式记录的一致性与规范性Authelia 提供了authelia-gen生成器工具链而本文聚焦其中的authelia-gen docs manage adr命令它负责生成、新增一份符合官方模板的架构决策记录ADR。读完本文你将掌握该命令的完整选项、它与adr add子命令的分工、底层实现如何自动编号并调用git add以及一份合法 ADR 文档应有的章节结构。命令概览作用与定位authelia-gen docs manage adr是authelia-gen工具链中用于生成架构决策记录的命令。在命令层级上它处于如下位置可对照 cmd_docs.go 中newDocsCmd与newDocsManageCmd的注册逻辑authelia-gen └── docs # Generate docs └── manage # Generate Managed docs └── adr # Generate an Architecture Decision Record └── add # Add an Architecture Decision Record从源码看cmd_docs.go 中newDocsManageCmd通过cmd.AddCommand(newADRCmd())挂载了adr子命令而 cmd_adr.go 中newADRCmd又挂载了add子命令。也就是说authelia-gen docs manage adr本身是一个命令分组namespace真正的写盘动作由其子命令add完成分组命令本身只提供-h, --help帮助选项不执行任何文件写入逻辑。该命令的官方描述为Generate an Architecture Decision Record生成一份架构决策记录对应参考文档位于 authelia-gen_docs_manage_adr.md。命令选项解析authelia-gen docs manage adr自身不接收业务参数仅提供帮助选项-h, --help help for adr真正的参数全部集中在其子命令authelia-gen docs manage adr add上详见 authelia-gen_docs_manage_adr_add.md。该子命令支持以下选项选项类型说明--title stringstring设置记录的标题--status stringstring设置记录的状态--context stringstring设置记录的上下文背景--proposed-design stringstring设置记录的拟议设计--decision stringstring设置记录作出的决策--consequences stringstring设置记录带来的后果--related-adrs intsint slice设置与本记录相关的其他 ADR 编号-h, --help-帮助这些选项与 cmd_adr.go 中cmd.Flags()的注册一一对应可直接通过cmd.Flags().GetString(...)/GetIntSlice(...)读取。继承自父命令的全局选项与authelia-gen的其他命令一样docs manage adr会继承父命令定义的全部全局选项。这些选项主要控制目录定位、文件路径与生成行为是理解该命令在哪里读写文件的关键-C, --cwd string Sets the CWD for git commands --dir.authentication string The authentication directory in relation to the root (default internal/authentication) --dir.docs string The directory with the docs (default docs) --dir.docs.adr string The directory with the ADR data (default reference/architecture-decision-log) --dir.docs.cli-reference string The directory to store the markdown in (default reference/cli) --dir.docs.content string The directory with the docs content (default content) --dir.docs.data string The directory with the docs data (default data) --dir.docs.static string The directory with the docs static files (default static) --dir.docs.static.json-schemas string The directory with the docs static JSONSchema files (default schemas) --dir.locales string The locales directory in relation to the root (default internal/server/locales) -d, --dir.root string The repository root (default ./) --dir.schema string The schema directory in relation to the root (default internal/configuration/schema) --dir.web string The repository web directory in relation to the root directory (default web) -X, --exclude strings Sets the names of excluded generators --file.bug-report string Sets the path of the bug report issue template file (default .github/ISSUE_TEMPLATE/bug-report.yml) --file.commit-lint-config string The commit lint javascript configuration file in relation to the root (default commitlint.config.mjs) --file.configuration-keys string Sets the path of the keys file (default internal/configuration/schema/keys.go) --file.docs-commit-msg-guidelines string The commit message guidelines documentation file in relation to the root (default docs/content/contributing/guidelines/commit-message.md) --file.docs.data.keys string Sets the path of the docs keys file (default configkeys.json) --file.docs.data.languages string The languages docs data file in relation to the docs data folder (default languages.json) --file.docs.data.misc string The misc docs data file in relation to the docs data folder (default misc.json) --file.docs.static.json-schemas.configuration string Sets the path of the configuration JSONSchema (default configuration) --file.docs.static.json-schemas.exports.identifiers string Sets the path of the identifiers export JSONSchema (default exports.identifiers) --file.docs.static.json-schemas.exports.totp string Sets the path of the TOTP export JSONSchema (default exports.totp) --file.docs.static.json-schemas.exports.webauthn string Sets the path of the WebAuthn export JSONSchema (default exports.webauthn) --file.docs.static.json-schemas.user-database string Sets the path of the user database JSONSchema (default user-database) --file.feature-request string Sets the path of the feature request issue template file (default .github/ISSUE_TEMPLATE/feature-request.yml) --file.scripts.gen string Sets the path of the authelia-scripts gen file (default cmd/authelia-scripts/cmd/gen.go) --file.server.generated string Sets the path of the server generated file (default internal/server/gen.go) --file.web.i18n string The i18n typescript configuration file in relation to the web directory (default src/i18n/index.ts) --file.web.package string The node package configuration file in relation to the web directory (default package.json) --latest Enables latest functionality with several generators like the JSON Schema generator --next Enables next functionality with several generators like the JSON Schema generator --package.configuration.keys string Sets the package name of the keys file (default schema) --package.scripts.gen string Sets the package name of the authelia-scripts gen file (default cmd) --version-count int the maximum number of minor versions to list in output templates (default 5) --versions strings The versions to run the generator for, the special versions current and next are mutually exclusive其中与本命令最相关的是--dir.docs.adrADR 数据目录默认reference/architecture-decision-log。该默认值在 const.go 中定义为dirDocsADR reference/architecture-decision-log而 ADR 文档实际存放位置为 docs/content/reference/architecture-decision-log/两者配合使用--dir.docs默认为docs--dir.docs.content默认为content最终由getPFlagPath拼接出完整路径。从源码看 ADR 的生成流程authelia-gen docs manage adr add的核心逻辑实现在 cmd_adr.go 的adrAddRunE函数中整个流程清晰且自动化定位 ADR 目录通过getPFlagPath(cmd.Flags(), cmdFlagRoot, cmdFlagDocs, cmdFlagDocsContent, cmdFlagDocsADR)拼出 ADR 所在目录读取配置读取该目录下的.adr.config.json配置文件反序列化为ArchitectureDesignRecordConfig结构体仅含next_id字段见 cmd_adr.go。注意该文件是命令运行时维护的本地状态文件不在仓库内提交组装模板数据构建ArchitectureDesignRecordTmpl见 cmd_adr.go其中ADR取配置中的NextIDWeight计算为1000 NextID与 Hugo 文档站点的权重机制对齐现有 ADR 如1.md的 weight 为 1001可相互印证日期自动取当前时间分别格式化出 YAML 时间戳、ISO 日期和人类可读日期校验关联 ADR遍历--related-adrs传入的编号若任一编号 config.NextID则直接报错related adr %d does not exist yet防止引用尚不存在的记录写入文件以NextID.md命名创建文件例如第 3 条记录生成3.md执行tmplADR模板渲染递增并回写配置config.NextID 1后以 0600 权限截断重写.adr.config.json保证下一个 ADR 编号连续自动 git 暂存最后执行git add 新文件cmd_adr.go新生成的 ADR 会被直接加入暂存区方便随 MR 一起提交。// cmd/authelia-gen/cmd_adr.go节选 data : ArchitectureDesignRecordTmpl{ ADR: config.NextID, Weight: 1000 config.NextID, Date: time.Now().Format(dateFmtYAML), DateISO: time.Now().Format(time.DateOnly), DateHuman: time.Now().Format(January 2, 2006), }ADR 文档的模板结构新生成的 ADR 并非空白文件而是由模板 docs-architectural_design_record.md.tmpl 渲染而成。该模板定义了 ADR 的完整骨架既包含 Hugo 前端元数据title、description、date、weight、toc、seo也包含 ADR 正文的标准章节Date记录发布日期人类可读格式Status记录状态未提供时默认ProposedSubmitters提交者姓名、链接与所属组织模板中为占位符需要人工填写Change Log变更日志表格含日期、PR、状态、备注四列首次发布时状态默认ProposedContext为什么需要这份 ADR 及其背景未提供时显示_N/A_Proposed Design拟议的设计方案未提供时显示_N/A_Decision最终作出的决策未提供时显示_N/A_Consequences该决策可能带来的不良后果未提供时显示_N/A_Related ADRs相关 ADR 列表模板按传入编号生成指向N.md的链接无相关记录时显示_N/A_。模板中引用的章节正是 introduction.md 中定义的 ADR 关键区块表Status、Context、Proposed Design、Decision、Consequences、Related ADRs。二者相互印证构成 Authelia 架构决策记录的标准格式。实操示例新增一条 ADR结合上文一条完整的实操命令如下假设在仓库根目录执行authelia-gen docs manage adr add \ --title Example: Replace Backing Authentication Service \ --status Proposed \ --context This record describes the context for an example decision. \ --proposed-design A description of the proposed design. \ --decision A description of the decision made. \ --consequences A description of the consequences. \ --related-adrs 1执行后工具会在docs/content/reference/architecture-decision-log/目录下生成形如4.md的文件编号取决于.adr.config.json中的next_id自动填充日期、weight、状态与各章节并通过git add完成暂存。若--related-adrs引用了尚未存在的编号如当前最大编号为 3 却引用 5命令会立即报错终止。与现有 ADR 的对应关系仓库中已提交的 ADR 正是上述模板的产物可作为格式参考ADR1: OpenID Connect Client Authorization Policies展示了完整的 StatusAccepted、Submitters、Change Log、Context、Proposed Design、Decision、Consequences 章节其 front matter 中weight: 1001与源码1000 NextID的计算规则完全吻合目录索引见 architecture-decision-log/_index.md其层级说明见 introduction.md。SEE ALSO命令导航authelia-gen docs manage adr在参考文档中与以下命令互为导航对应 authelia-gen_docs_manage_adr.md 的 SEE ALSO 段落authelia-gen docs manage父命令Generate Managed docsauthelia-gen docs manage adr add子命令Add an Architecture Decision Record。需要理解整个authelia-gen工具链时可从 authelia-gen.md 与 docs 命令组 入手继续阅读。小结authelia-gen docs manage adr是 Authelia 将架构决策纳入工程化文档体系的重要一环它以固定模板统一 ADR 的章节结构以.adr.config.json维护记录编号以git add衔接版本控制流程。对维护者而言这意味着新增一条架构决策记录只需一条命令加若干参数对读者而言所有 ADR 都遵循一致的 Status / Context / Proposed Design / Decision / Consequences 结构便于检索、引用与追溯。结合 cmd_adr.go 与 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考