Authelia authelia-gen code scripts 命令详解自动生成 authelia-scripts 的 Swagger UI 版本常量【免费下载链接】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-gen code scripts是 Authelia 代码生成工具链authelia-gen中用于生成authelia-scripts命令生成部分的子命令。它的核心职责是查询 Swagger UI 的最新发布版本并将版本号写入cmd/authelia-scripts/cmd/gen.go供后续构建脚本在打包 API 文档页面时使用。读完本文你将掌握该命令的完整用法、全部可用参数及其默认值并能从源码层面理解它如何与 Swagger UI 的发布流程、authelia-scripts 的构建流程协同工作。命令概览它生成什么为什么需要它authelia-gen code scripts是 authelia-gen code 的三个子命令之一另外两个是keys与server。它的官方描述是Generate the generated portion of the authelia-scripts command所谓authelia-scripts 命令的生成部分指的是 cmd/authelia-scripts/cmd/gen.go 这个文件——它由代码生成器产出不应被手工修改文件头部明确标注了生成来源// Code generated by go generate. DO NOT EDIT. // // Run the following command to generate this file: // go run ./cmd/authelia-gen code scripts // package cmd const ( versionSwaggerUI 5.32.15 )该文件唯一的有效载荷是一个常量versionSwaggerUI它记录了 Authelia 内置 API 文档所捆绑的 Swagger UI 版本。这个常量随后被 build.go 中的buildSwagger()函数消费脚本据此从 GitHub 下载对应版本的 Swagger UI 压缩包解压其dist目录并剔除部分文件后发布到internal/server/public_html/api下成为 Authelia 门户内置的 OpenAPI 交互式文档界面。命令用法authelia-gen code scripts [flags]在仓库根目录下也可以直接通过go run执行这也是生成文件头部注释推荐的调用方式go run ./cmd/authelia-gen code scripts本地选项该命令自身只暴露一个本地选项选项说明-h, --help显示scripts子命令的帮助信息除此之外它不接收任何位置参数。注意由于authelia-gen code使用rootSubCommandsRunE作为运行入口见 cmd_code.go直接执行authelia-gen code会按字母序依次运行其全部子命令keys、scripts、server因此当你只想单独刷新gen.go时必须显式指定scripts子命令。从父命令继承的全局选项code scripts的所有其他选项均继承自authelia-gen根命令定义于 cmd_root.go以及code父命令属于持久化persistent标志。这些选项控制着工具运行时的目录基准、目标文件路径与版本行为对自定义生成流程至关重要。目录相关选项选项说明默认值-C, --cwd string为 git 命令设置当前工作目录CWD空-d, --dir.root string仓库根目录./--dir.authentication string认证目录相对根目录internal/authentication--dir.docs string文档目录docs--dir.docs.adr stringADR 数据目录reference/architecture-decision-log--dir.docs.cli-reference string存放 CLI 参考 markdown 的目录reference/cli--dir.docs.content string文档内容目录content--dir.docs.data string文档数据目录data--dir.docs.static string文档静态文件目录static--dir.docs.static.json-schemas string文档静态 JSONSchema 文件目录schemas--dir.locales stringlocales 目录相对根目录internal/server/locales--dir.schema string配置 schema 目录相对根目录internal/configuration/schema--dir.web stringWeb 目录相对根目录web文件路径选项选项说明默认值--file.bug-report stringbug report issue 模板文件路径.github/ISSUE_TEMPLATE/bug-report.yml--file.commit-lint-config stringcommit lint JavaScript 配置文件相对根目录commitlint.config.mjs--file.configuration-keys string配置 keys 文件路径internal/configuration/schema/keys.go--file.docs-commit-msg-guidelines stringcommit message 规范文档相对根目录docs/content/contributing/guidelines/commit-message.md--file.docs.data.keys string文档 keys 数据文件路径configkeys.json--file.docs.data.languages stringlanguages 文档数据文件相对 docs data 目录languages.json--file.docs.data.misc stringmisc 文档数据文件相对 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 string服务端生成文件路径internal/server/gen.go--file.web.i18n stringi18n TypeScript 配置文件相对 web 目录src/i18n/index.ts--file.web.package stringnode package 配置文件相对 web 目录package.json其中与code scripts直接相关的是--file.scripts.gen它决定生成文件写到哪个位置相关常量定义见 const.go。包名与版本行为选项选项说明默认值--package.configuration.keys stringkeys 文件的包名schema--package.scripts.gen stringauthelia-scripts gen 文件的包名cmd--latest为多个生成器如 JSON Schema 生成器启用 latest 功能false--next为多个生成器如 JSON Schema 生成器启用 next 功能false--version-count int输出模板中列出的 minor 版本最大数量5--versions strings要运行生成器的版本列表特殊版本current与next互斥空-X, --exclude strings设置被排除的生成器名称空对code scripts而言--package.scripts.gen直接决定生成文件中package语句的取值——模板中通过{{ .Package }}注入见下文模板分析默认值为cmd与cmd/authelia-scripts/cmd/gen.go现有的包声明一致。源码级执行原理code scripts的运行逻辑集中在 cmd_code.go 的codeScriptsRunE函数中整体流程可分为四步读取参数从命令行标志中读取--dir.root、--file.scripts.gen与--package.scripts.gen三个标志分别赋值给root、pathScriptsGen与data.Package查询最新版本通过http.Get请求 GitHub APIhttps://api.github.com/repos/swagger-api/swagger-ui/releases/latest将响应体解析为GitHubReleasesJSON结构取出其中的TagName字段若该字段以v开头则剥离前缀得到纯净的版本号例如5.32.15存入data.VersionSwaggerUI。这一步意味着命令执行时需要外网连通性无法访问 GitHub API 时命令会以错误终止组合输出路径使用filepath.Join(root, pathScriptsGen)将仓库根目录与相对路径拼接为最终输出文件的绝对/相对路径然后以os.Create创建若已存在则截断覆盖渲染模板并写出将数据对象传入预编译模板tmplScriptsGen注册于 templates.go对应模板文件 cmd-authelia-scripts-gen.go.tmpl执行后写入文件并关闭。模板与数据模型生成文件的内容由 Go 文本模板 cmd-authelia-scripts-gen.go.tmpl 决定// SPDX-FileCopyrightText: 2026 Authelia // // SPDX-License-Identifier: Apache-2.0 // Code generated by go generate. DO NOT EDIT. // // Run the following command to generate this file: // go run ./cmd/authelia-gen code scripts // package {{ .Package }} const ( versionSwaggerUI {{ .VersionSwaggerUI }} )模板仅使用两个占位符对应的数据模型定义于 types.gotype tmplScriptsGEnData struct { Package string VersionSwaggerUI string }也就是说整个生成过程本质上是一次网络查询 常量落盘把一个来自上游发布页的动态版本号固化为本地源码中的编译期常量。生成产物的下游消费构建期如何联动生成的 gen.go 在构建阶段被 build.go 的buildSwagger()使用。其典型调用链为用wget下载https://github.com/swagger-api/swagger-ui/archive/v${versionSwaggerUI}.tar.gz到本地用tar解压压缩包内的swagger-ui-${versionSwaggerUI}/dist目录到internal/server/public_html/api同时排除index.html、*.map、*-es-*及swagger-{ui,initializer}.js等文件删除下载的压缩包。这意味着authelia-gen code scripts是 Authelia 内置 API 文档OpenAPI UI版本升级链路的第一环先由生成器锁定 Swagger UI 版本再由 authelia-scripts 构建命令据此拉取并嵌入对应资源。因此从源码结构看该命令承担的是版本事实的唯一来源角色——任何手工修改gen.go中的版本号都会在下次运行生成器时被覆盖正确的升级方式是运行authelia-gen code scripts让工具自动同步上游最新版本。实践建议与注意事项运行环境要求命令依赖外网访问api.github.com在离线或受限网络环境下会报failed to get latest version of the Swagger UI错误单独运行子命令authelia-gen code会依次执行 keys、scripts、server 三个子命令若只想更新 Swagger UI 版本常量务必使用完整的go run ./cmd/authelia-gen code scripts版本号规范GitHub 返回的tag_name若带v前缀会被自动剥离见 cmd_code.go因此生成文件中的常量始终是不带前缀的纯版本号不要手工编辑产物gen.go 头部带有 DO NOT EDIT 标记应始终通过生成器再生成。相关命令code scripts隶属于authelia-gen code命令族如需进一步了解其兄弟命令可参考authelia-gen code — Generate codecode 命令族总览authelia-gen — Authelia 的生成器工具链根命令包含commit-lint、docs、github、locales、misc、release、contributors等全部子命令【免费下载链接】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），仅供参考