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导读本文聚焦 Authelia 项目为文档贡献者制定的编写规范见 docs/content/contributing/guidelines/documentation.md系统讲解文档中「域名使用」「证书示例」「私钥示例」三条硬性规则及其背后的安全与可维护性考量并结合仓库内文档体系、authelia-gen文档生成器与crypto证书生成命令的源码与配置实例帮助贡献者在提交 PR 前一次通过文档审查。读完本文你将掌握 Authelia 文档示例素材域名、证书、私钥的标准化制作方法理解为什么证书有效期要锚定Jan 1 00:00:00 1970以及如何用^invalid DO NOT USE标记让示例私钥既无法被解析、又明确传达“禁止使用”的语义。规范在 Authelia 贡献体系中的位置Authelia 的贡献指南分为多个部分见 docs/content/contributing/guidelines/_index.md其中guidelines/documentation.md是专门约束文档内容素材规范的页面。与同目录下的 accessibility.md、commit-message.md、style.md 等指南一样它由 CI 与人工审查共同执行——项目在 docs/content/contributing/guidelines/introduction.md 中明确说明指南的一部分会通过自动化流程在 PR 中给出反馈但自动化并不能覆盖所有场景其余部分依赖人工审查。该文档全文围绕三个主题展开语言简洁、规则明确是 Authelia 文档质量的底层保障Domains域名规范——示例一律使用example.comCertificates证书规范——示例证书有效期固定为 1 年、起始于Jan 1 00:00:00 1970Private Keys私钥规范——PEM 块末尾必须追加无效数据标记^invalid DO NOT USE。以下逐条展开并结合仓库实际用法佐证。域名规范一律使用保留域名example.com规则原文与意图Always use the generic domain (or subdomain of)example.comin documentation.文档中的任何示例域名必须使用通用保留域名example.com或其子域如auth.example.com。example.com是由 IANA 保留、专门用于文档与示例的域名不会被真实组织或个人注册使用因此可以彻底避免示例配置被读者误当真值、或与真实业务域名发生冲突。如果确实需要在一个文档中出现多个不同域名规范要求在 PR 中主动向维护者说明并获得反馈If its necessary to utilize more than one domain please ask for specific feedback in any PR.这一条的目的在于多域名场景往往意味着复杂的跨域配置Cookie 域、CORS、OIDC issuer 等维护者需要针对具体上下文给出建议避免贡献者自行引入可能误导读者的域名组合。仓库中的实际执行情况example.com规范在 Authelia 文档与工具链中贯彻得非常彻底在 Traefik 部署教程中所有服务均归属example.com域Authelia 门户使用auth.example.com子域见 docs/content/blog/authelia-traefik-setup-guide/index.md在 OIDC 技术细节文章中issuer、audience 等取值统一为https://auth.example.com、https://auth.example.com/api/oidc/introspection见 docs/content/blog/technical-oidc-nuances/index.md文档站点还提供了{{ sitevar namedomain nojsexample.com }}这类 Hugo Shortcode 用法见 docs/content/contributing/prologue/documentation-contributions.md 对 Shortcodes 的介绍使读者可以按需替换为真实域名就连authelia-gen工具自身的默认参数也遵循该约定例如 OIDC 一致性测试计划默认使用https://auth.example.com与https://conformance.example.com见 cmd/authelia-gen/cmd_misc.go。对于贡献者而言最直接的落地方式就是在撰写或修改文档时把所有示例域名统一写成example.com或它的子域只有在文档主题本身要求演示多域名行为如多 Cookie 域场景时才引入第二个域名并在 PR 描述中说明理由。证书规范有效期锚定Jan 1 00:00:00 1970跨度 1 年规则原文与意图When including certificates in documentation always ensure they are valid for 1 year starting atJan 1 00:00:00 1970. This ensures the certificate is not valid for multiple reasons.文档中出现的示例证书其有效期必须满足两个条件起始时间Jan 1 00:00:00 1970Unix 纪元起点有效期长度恰好 1 年即终止于Jan 1 00:00:00 1971。这样设计的核心动机是让证书“确定无效”且“无效原因唯一”。如果示例证书的有效期覆盖真实时间例如 2020–2030那么它在读者所在的当下是“有效”的一旦被误用于生产环境会引发一连串难以排查的问题而把有效期固定在 1970–1971 年任何 TLS 校验都会立刻失败读者和自动化工具都能一眼识别“这是示例不可使用”。同时1 年跨度配合固定起点也保证了所有示例证书的形态完全一致、可预期、便于审阅。与 crypto 命令生成示例的对应关系仓库的配置测试资源正是用 Authelia 自带的crypto certificate命令生成证书的生成脚本位于 internal/configuration/test_resources/crypto/gen.sh。脚本中 RSA 1024 示例的生成命令如下go run ./cmd/authelia crypto certificate rsa generate \ --bits1024 \ --directory./internal/configuration/test_resources/crypto \ --file.ca-certificateca.rsa.1024.crt \ --file.ca-private-keyca.rsa.1024.pem \ -nAuthelia Development RSA 1024 Standalone Root CA \ --not-beforeJan 1 00:00:00 2000 \ --not-afterJan 1 00:00:00 2100 \ -oAuthelia \ --organizational-unitDevelopment \ --ca --legacy该脚本为仓库内证书/私钥测试资源设定了--not-beforeJan 1 00:00:00 2000与--not-afterJan 1 00:00:00 2100的 100 年跨度便于各类测试场景复用。而文档规范要求的则是更严格的 1 年有效期1970-01-01 起。两者并不矛盾文档规范针对的是写进文档正文的示例证书——它们必须“一眼可见地无效”而test_resources中的证书服务于自动化测试其有效期需求由测试场景决定。贡献者向文档中粘贴证书时应生成有效期锚定 1970 年的专用示例而不是直接拷贝test_resources中跨度 100 年的证书。crypto certificate命令支持 RSA、ECDSAP224/P256/P384/P521与 Ed25519 等多种算法见同一脚本且均接受--not-before/--not-after参数贡献者完全可以按文档规范用一条命令产出合规示例go run ./cmd/authelia crypto certificate rsa generate \ --bits2048 \ --sansexample.com \ --not-beforeJan 1 00:00:00 1970 \ --not-afterJan 1 00:00:00 1971 \ -oAuthelia --organizational-unitDevelopment私钥规范在 PEM 块末尾追加^invalid DO NOT USE标记规则原文与意图Always append invalid data to the END of the PEM block before the base64 padding(if present). The suggested text is^invalid DO NOT USE. This both has an invalid base64 character^and has information to communicate that users should not use the PEM block.文档中出现任何 PEM 格式私钥时必须向 PEM 块内部追加无效数据追加位置是PEM 块内容的末尾即-----END ... PRIVATE KEY-----之前若内容末尾存在 base64 填充字符则追加在之前。推荐追加的文本为^invalid DO NOT USE。这段文本同时达成两个目的技术层面破坏有效性^不是合法的 base64 字符任何严格的 base64 解码都会失败私钥因此无法被解析加载从机制上杜绝被误用语义层面明确警示DO NOT USE直接向阅读文档的读者传达“此私钥禁止使用”的信息即使有人手工复制粘贴也能看到醒目警告。正确与错误的追加位置对比以一段示意性的PEM 私钥为例规范要求的最终形态是-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEA... 省略的 base64 内容 ...Q^invalid DO NOT USE -----END RSA PRIVATE KEY-----需要注意几个细节^invalid DO NOT USE必须位于最后一个若有之前——因为它本身不是合法 base64若放在之后、PEM 结束行之前同样会破坏解码但规范明确要求放在填充符之前以保证所有示例形态统一若 PEM 内容末尾没有填充base64 编码长度恰好是 3 的倍数时则直接追加在内容末尾即可“if present” 即为此意该标记同样适用于文档中出现的证书场景certificates 一节明确要求“In addition the guidance for Private Keys should be followed”即证书文档中若附带私钥同样必须执行此标记规则。三条规范的综合实操清单把以上三条规则放到一次实际的文档贡献流程中完整的自查清单如下域名全文示例域名统一为example.com或其子域确需多域名时在 PR 描述中向维护者说明并等待反馈参考 docs/content/contributing/guidelines/documentation.md证书示例证书有效期固定为Jan 1 00:00:00 1970起的 1 年可用crypto certificate ... generate --not-beforeJan 1 00:00:00 1970 --not-afterJan 1 00:00:00 1971生成命令能力见 internal/configuration/test_resources/crypto/gen.sh私钥每个 PEM 私钥在填充符之前追加^invalid DO NOT USE同时破坏 base64 解码并给出文字警示整体质量修改文档后运行source bootstrap.sh authelia-gen --exclude docs.date,docs.cli让生成器同步相关数据与 Front Matter 日期流程说明见 docs/content/contributing/prologue/documentation-contributions.md并在本地用pnpm dev预览确认渲染无误。延伸为什么这些细节值得严格遵守表面看这三条规范只是“示例素材的格式约定”但它们的价值远超格式本身防止示例被误用为生产配置example.com无法被真实注册1970 年的证书必然校验失败^invalid DO NOT USE直接让私钥不可解析——三层防护叠加最大限度降低读者把示例配置抄进生产环境的概率这正是安全项目文档应有的自觉保证文档可审阅、可自动化校验固定起止时间、固定标记文本使得 CI 与维护者可以用确定性规则检查文档符合 docs/content/contributing/guidelines/introduction.md 中“通过自动流程在 PR 中反馈”的指南执行方式维护项目一致性Authelia 文档体量庞大docs/content下含 configuration、integration、reference 等数百个页面统一的示例素材规范让所有页面风格一致也方便读者和 Agent 检索时建立稳定的认知模式。如果你准备为 Authelia 贡献文档请牢记这份三行规范域名用example.com证书锚定 1970 年 1 月 1 日起 1 年私钥末尾追加^invalid DO NOT USE——它们是文档通过审查的最低门槛也是 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），仅供参考 Authelia 文档编写规范指南：域名、证书与私钥示例的贡献守则
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导读本文聚焦 Authelia 项目为文档贡献者制定的编写规范见 docs/content/contributing/guidelines/documentation.md系统讲解文档中「域名使用」「证书示例」「私钥示例」三条硬性规则及其背后的安全与可维护性考量并结合仓库内文档体系、authelia-gen文档生成器与crypto证书生成命令的源码与配置实例帮助贡献者在提交 PR 前一次通过文档审查。读完本文你将掌握 Authelia 文档示例素材域名、证书、私钥的标准化制作方法理解为什么证书有效期要锚定Jan 1 00:00:00 1970以及如何用^invalid DO NOT USE标记让示例私钥既无法被解析、又明确传达“禁止使用”的语义。规范在 Authelia 贡献体系中的位置Authelia 的贡献指南分为多个部分见 docs/content/contributing/guidelines/_index.md其中guidelines/documentation.md是专门约束文档内容素材规范的页面。与同目录下的 accessibility.md、commit-message.md、style.md 等指南一样它由 CI 与人工审查共同执行——项目在 docs/content/contributing/guidelines/introduction.md 中明确说明指南的一部分会通过自动化流程在 PR 中给出反馈但自动化并不能覆盖所有场景其余部分依赖人工审查。该文档全文围绕三个主题展开语言简洁、规则明确是 Authelia 文档质量的底层保障Domains域名规范——示例一律使用example.comCertificates证书规范——示例证书有效期固定为 1 年、起始于Jan 1 00:00:00 1970Private Keys私钥规范——PEM 块末尾必须追加无效数据标记^invalid DO NOT USE。以下逐条展开并结合仓库实际用法佐证。域名规范一律使用保留域名example.com规则原文与意图Always use the generic domain (or subdomain of)example.comin documentation.文档中的任何示例域名必须使用通用保留域名example.com或其子域如auth.example.com。example.com是由 IANA 保留、专门用于文档与示例的域名不会被真实组织或个人注册使用因此可以彻底避免示例配置被读者误当真值、或与真实业务域名发生冲突。如果确实需要在一个文档中出现多个不同域名规范要求在 PR 中主动向维护者说明并获得反馈If its necessary to utilize more than one domain please ask for specific feedback in any PR.这一条的目的在于多域名场景往往意味着复杂的跨域配置Cookie 域、CORS、OIDC issuer 等维护者需要针对具体上下文给出建议避免贡献者自行引入可能误导读者的域名组合。仓库中的实际执行情况example.com规范在 Authelia 文档与工具链中贯彻得非常彻底在 Traefik 部署教程中所有服务均归属example.com域Authelia 门户使用auth.example.com子域见 docs/content/blog/authelia-traefik-setup-guide/index.md在 OIDC 技术细节文章中issuer、audience 等取值统一为https://auth.example.com、https://auth.example.com/api/oidc/introspection见 docs/content/blog/technical-oidc-nuances/index.md文档站点还提供了{{ sitevar namedomain nojsexample.com }}这类 Hugo Shortcode 用法见 docs/content/contributing/prologue/documentation-contributions.md 对 Shortcodes 的介绍使读者可以按需替换为真实域名就连authelia-gen工具自身的默认参数也遵循该约定例如 OIDC 一致性测试计划默认使用https://auth.example.com与https://conformance.example.com见 cmd/authelia-gen/cmd_misc.go。对于贡献者而言最直接的落地方式就是在撰写或修改文档时把所有示例域名统一写成example.com或它的子域只有在文档主题本身要求演示多域名行为如多 Cookie 域场景时才引入第二个域名并在 PR 描述中说明理由。证书规范有效期锚定Jan 1 00:00:00 1970跨度 1 年规则原文与意图When including certificates in documentation always ensure they are valid for 1 year starting atJan 1 00:00:00 1970. This ensures the certificate is not valid for multiple reasons.文档中出现的示例证书其有效期必须满足两个条件起始时间Jan 1 00:00:00 1970Unix 纪元起点有效期长度恰好 1 年即终止于Jan 1 00:00:00 1971。这样设计的核心动机是让证书“确定无效”且“无效原因唯一”。如果示例证书的有效期覆盖真实时间例如 2020–2030那么它在读者所在的当下是“有效”的一旦被误用于生产环境会引发一连串难以排查的问题而把有效期固定在 1970–1971 年任何 TLS 校验都会立刻失败读者和自动化工具都能一眼识别“这是示例不可使用”。同时1 年跨度配合固定起点也保证了所有示例证书的形态完全一致、可预期、便于审阅。与 crypto 命令生成示例的对应关系仓库的配置测试资源正是用 Authelia 自带的crypto certificate命令生成证书的生成脚本位于 internal/configuration/test_resources/crypto/gen.sh。脚本中 RSA 1024 示例的生成命令如下go run ./cmd/authelia crypto certificate rsa generate \ --bits1024 \ --directory./internal/configuration/test_resources/crypto \ --file.ca-certificateca.rsa.1024.crt \ --file.ca-private-keyca.rsa.1024.pem \ -nAuthelia Development RSA 1024 Standalone Root CA \ --not-beforeJan 1 00:00:00 2000 \ --not-afterJan 1 00:00:00 2100 \ -oAuthelia \ --organizational-unitDevelopment \ --ca --legacy该脚本为仓库内证书/私钥测试资源设定了--not-beforeJan 1 00:00:00 2000与--not-afterJan 1 00:00:00 2100的 100 年跨度便于各类测试场景复用。而文档规范要求的则是更严格的 1 年有效期1970-01-01 起。两者并不矛盾文档规范针对的是写进文档正文的示例证书——它们必须“一眼可见地无效”而test_resources中的证书服务于自动化测试其有效期需求由测试场景决定。贡献者向文档中粘贴证书时应生成有效期锚定 1970 年的专用示例而不是直接拷贝test_resources中跨度 100 年的证书。crypto certificate命令支持 RSA、ECDSAP224/P256/P384/P521与 Ed25519 等多种算法见同一脚本且均接受--not-before/--not-after参数贡献者完全可以按文档规范用一条命令产出合规示例go run ./cmd/authelia crypto certificate rsa generate \ --bits2048 \ --sansexample.com \ --not-beforeJan 1 00:00:00 1970 \ --not-afterJan 1 00:00:00 1971 \ -oAuthelia --organizational-unitDevelopment私钥规范在 PEM 块末尾追加^invalid DO NOT USE标记规则原文与意图Always append invalid data to the END of the PEM block before the base64 padding(if present). The suggested text is^invalid DO NOT USE. This both has an invalid base64 character^and has information to communicate that users should not use the PEM block.文档中出现任何 PEM 格式私钥时必须向 PEM 块内部追加无效数据追加位置是PEM 块内容的末尾即-----END ... PRIVATE KEY-----之前若内容末尾存在 base64 填充字符则追加在之前。推荐追加的文本为^invalid DO NOT USE。这段文本同时达成两个目的技术层面破坏有效性^不是合法的 base64 字符任何严格的 base64 解码都会失败私钥因此无法被解析加载从机制上杜绝被误用语义层面明确警示DO NOT USE直接向阅读文档的读者传达“此私钥禁止使用”的信息即使有人手工复制粘贴也能看到醒目警告。正确与错误的追加位置对比以一段示意性的PEM 私钥为例规范要求的最终形态是-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEA... 省略的 base64 内容 ...Q^invalid DO NOT USE -----END RSA PRIVATE KEY-----需要注意几个细节^invalid DO NOT USE必须位于最后一个若有之前——因为它本身不是合法 base64若放在之后、PEM 结束行之前同样会破坏解码但规范明确要求放在填充符之前以保证所有示例形态统一若 PEM 内容末尾没有填充base64 编码长度恰好是 3 的倍数时则直接追加在内容末尾即可“if present” 即为此意该标记同样适用于文档中出现的证书场景certificates 一节明确要求“In addition the guidance for Private Keys should be followed”即证书文档中若附带私钥同样必须执行此标记规则。三条规范的综合实操清单把以上三条规则放到一次实际的文档贡献流程中完整的自查清单如下域名全文示例域名统一为example.com或其子域确需多域名时在 PR 描述中向维护者说明并等待反馈参考 docs/content/contributing/guidelines/documentation.md证书示例证书有效期固定为Jan 1 00:00:00 1970起的 1 年可用crypto certificate ... generate --not-beforeJan 1 00:00:00 1970 --not-afterJan 1 00:00:00 1971生成命令能力见 internal/configuration/test_resources/crypto/gen.sh私钥每个 PEM 私钥在填充符之前追加^invalid DO NOT USE同时破坏 base64 解码并给出文字警示整体质量修改文档后运行source bootstrap.sh authelia-gen --exclude docs.date,docs.cli让生成器同步相关数据与 Front Matter 日期流程说明见 docs/content/contributing/prologue/documentation-contributions.md并在本地用pnpm dev预览确认渲染无误。延伸为什么这些细节值得严格遵守表面看这三条规范只是“示例素材的格式约定”但它们的价值远超格式本身防止示例被误用为生产配置example.com无法被真实注册1970 年的证书必然校验失败^invalid DO NOT USE直接让私钥不可解析——三层防护叠加最大限度降低读者把示例配置抄进生产环境的概率这正是安全项目文档应有的自觉保证文档可审阅、可自动化校验固定起止时间、固定标记文本使得 CI 与维护者可以用确定性规则检查文档符合 docs/content/contributing/guidelines/introduction.md 中“通过自动流程在 PR 中反馈”的指南执行方式维护项目一致性Authelia 文档体量庞大docs/content下含 configuration、integration、reference 等数百个页面统一的示例素材规范让所有页面风格一致也方便读者和 Agent 检索时建立稳定的认知模式。如果你准备为 Authelia 贡献文档请牢记这份三行规范域名用example.com证书锚定 1970 年 1 月 1 日起 1 年私钥末尾追加^invalid DO NOT USE——它们是文档通过审查的最低门槛也是 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），仅供参考