Authelia 集成测试套件Integration Suites完全指南从环境搭建到并发运行与自定义套件开发【免费下载链接】autheliaThe Single Sign-On Multi-Factor portal for web apps. OpenID Certified™ and Post-Quantum Cryptography Ready.项目地址: https://gitcode.com/GitHub_Trending/au/autheliaAuthelia 是单点登录生态中的一个组件其功能必须与 NGINX、Redis、MariaDB、Traefik、HAProxy 等外部组件协同才能被完整验证。为此Authelia 提出了Suite套件概念一种为 Authelia 及其配套组件准备的虚拟化测试环境。本文以 integration-suites.md 为核心结合 internal/suites 与 cmd/authelia-scripts 的源码实现完整讲解如何启动、访问、调试、并发运行套件以及如何从零创建一个新套件。重要前提本文所有操作均假设你已经完成了 环境准备Prerequisites并已通过 bootstrap.sh 引导进入Authelia 开发上下文Development Context。什么是 Integration SuiteAuthelia 是一个与许多外部系统交互的组件因此其功能测试并不像单机程序那样简单。Suite 正是为了解决这一问题而生的抽象它是一个由 Docker Compose 编排的虚拟环境 一组针对该环境的测试。一个 Suite 可以拉起 NGINX、Redis、MariaDB、LDAP、Traefik、HAProxy、Kubernetes 等组件让 Authelia 在其中真实运行并被测试。这套抽象同时服务于两个场景开发期手动测试为开发者准备一套完整的、可交互的本地环境集成测试高效地编写并运行自动化集成测试基于 Selenium/chromedriver 驱动真实浏览器。从源码结构看套件的核心实现位于 internal/suites 目录suite_name.go定义环境生命周期suite_name_test.go定义测试用例同名目录存放资源文件详见后文创建新套件一节。启动一个 Suite启动名为Standalone的套件只需一条命令authelia-scripts suites setup Standalone该命令会执行套件的setup 阶段即通过docker compose部署整套环境。对应实现位于 cmd/authelia-scripts/cmd/suites.go 的cmdSuitesSetupRun它会先检查当前是否有其他套件正在运行通过工作树根目录下的.suite文件记录若存在且与目标套件不一致则直接拒绝启动随后调用setupSuite执行部署。以 Standalone 套件为例其 setup 定义在 internal/suites/suite_standalone.godockerEnvironment : NewDockerEnvironment([]string{ internal/suites/compose.yml, internal/suites/Standalone/compose.yml, internal/suites/example/compose/authelia/compose.backend.{}.yml, internal/suites/example/compose/authelia/compose.frontend.{}.yml, internal/suites/example/compose/nginx/backend/compose.yml, internal/suites/example/compose/nginx/portal/compose.yml, internal/suites/example/compose/smtp/compose.yml, }) setup : func(suitePath string) (err error) { if err dockerEnvironment.Up(); err ! nil { return err } if err waitUntilAutheliaIsReady(dockerEnvironment, standaloneSuiteName); err ! nil { return err } return updateDevEnvFileForDomain(BaseDomain, dockerEnvironment) }可以看到一个套件可以叠加多个 compose 文件基础网络、套件专属资源、后端注意{}占位符在 CI 环境下会被替换为dist见 internal/suites/docker.go、前端、反向代理NGINX portal以及 SMTP 邮件服务。部署完成后还会等待 Authelia 后端就绪再按BaseDomain更新开发环境文件。启动完成后所有容器会持续运行方便你进行手动探索或接着运行测试。访问套件环境开发套件采用标准化布局让交互变得非常一致。IP 地址BackendAuthelia 后端192.168.240.50Frontend前端 Web 服务器192.168.240.100其中 backend 是运行在 Docker 容器中的 Authelia 二进制frontend 则是托管所有应用 Web 前端的 Web 服务器含 NGINX、Traefik 等代理。这两处地址是本地开发的默认值。任何与其他套件共享同一个 Docker daemon 的运行即所有 CI agent以及开发机上第一个之外的工作树都会设置SUITE_SLOT从而获得独立的 compose project 与独立子网此时本文所有地址的前三个八位段都会随之改变。详见下文 并发运行 与 环境变量 两节。站点与应用所有站点都托管在地址${SUITE_SUBNET}.100:8080上本地开发即为192.168.240.100:8080。以下清单并非穷举且可能随时间变化完整的 host 条目配置请看 internal/suites/hosts.go其中HostEntries函数集中定义了所有套件域名到套件网络地址的映射。某个套件具体拉起哪些应用可查看该套件suite_name.go文件中的dockerEnvironment变量。Authelia 门户https://login.example.com:8080Mailpit邮件测试https://mail.example.com:8080OpenID Connect 1.0 测试应用https://oidc.example.com:8080https://oidc-public.example.com:8080Duohttps://duo.example.com:8080Kubernetes Dashboardhttps://kubernetes.example.com:8080Traefik Dashboardhttps://traefik.example.com:8080HAProxyhttps://haproxy.example.com:8080简单测试应用https://public.example.com:8080https://singlefactor.example.com:8080https://secure.example.com:8080https://admin.example.com:8080https://deny.example.com:8080注意这些站点均使用https且带自签名证书浏览器首次访问需要手动信任证书。除了上述常见站点hosts.go 还定义了网络 ACL 测试用的proxy-client1/2/3.example.com192.168.240.201~203、Redis 主从节点redis-node-0/1/2.example.com.110~112、Redis Sentinelredis-sentinel-0/1/2.example.com.120~122以及 PAM 套件的ssh.example.com.130。多 Cookie 域套件还会动态生成example2.com、example3.com下的全部子域条目见hostEntriesCookieDomains。环境变量一览当多个套件共享同一个 Docker daemon 时会并发运行多份副本以下环境变量用于隔离它们。每个变量都是可选的未设置时回退到单次本地运行的默认值。变量默认值用途SUITE_SLOT未设置该 agent 或工作树拥有的槽位号。设置后bootstrap.sh 会据此推导出COMPOSE_PROJECT_NAME、SUITE_SUBNET、LDAP_ADMIN_PORT、ENVOY_ADMIN_PORT在 CI 之外还会推导SUITE_TMP与SUITE_TMP_PATH。带槽位的 shell 不再改动/etc/hosts。SUITE_SLOT_AUTO未设置设为false可阻止bootstrap.sh为本工作树自动分配槽位。CI 中无效果因为 CI 的槽位由 agent 提供。COMPOSE_PROJECT_NAMEautheliaCompose 项目名。同时用于限定 Traefik 的 Docker provider 只发现属于本项目自己的容器见 internal/suites/docker.go 与autheliaNetworkName。SUITE_SUBNET192.168.240套件网络的前三个八位段。SuiteAddress(octet)用它与末位段拼出完整地址见 internal/suites/docker.go。SUITE_TMP/tmp绑定挂载进套件容器的主机目录容器内恒以/tmp看到它。每个 agent 或工作树应有自己的目录因为任务结束时该目录顶层除 agent 自身工作文件外的所有内容都会被清除。SUITE_TMP_PATH/tmp测试进程自身读写同一份内容的路径。CI 中保持/tmpSUITE_TMP被绑定到 agent 内的/tmp本地则设为SUITE_TMP测试进程跑在宿主机上。对应实现见 internal/suites/docker.go 的SuiteTmpPath。SUITE_IMAGEauthelia:dist后端容器运行的镜像。AGENT_CONTAINER未设置运行测试的容器名。设置后该容器会在 setup 时被连接到套件网络、teardown 时断开对应connectAgentNetwork/disconnectAgentNetwork见 internal/suites/docker.go从而让 Chrome 能访问到门户。并发运行多套件一台机器上可以同时运行多个套件每个 git 工作树working tree各占一个。在工作树中执行source bootstrap.sh即可为该工作树分配一个槽位并由此推导出所有可能冲突的资源[BOOTSTRAP] Using suite slot 2 for /home/user/authelia-feature槽位按工作树记忆之后每次source都得到同一个槽位当工作树被删除时槽位自动释放。查看或管理分配情况authelia-scripts suites slot --list authelia-scripts suites slot --release从源码看槽位分配由 cmd/authelia-scripts/cmd/slot.go 实现allocateSlot总是给工作树分配当前最小的未用编号--list输出形如2 /home/user/authelia-feature的登记表--release则从登记中移除当前工作树。登记表存放在工作树之外的$XDG_STATE_HOME/authelia/suite-slots未设置时回退到~/.local/state/authelia/suite-slots并通过文件锁flock保证并发分配安全——两个同时source的 shell 绝不会拿到同一个槽位读取登记表时会自动丢弃已不存在工作树的条目从而实现删除工作树即释放槽位。有了槽位号之后bootstrap.sh 推导出的关键派生值如下export COMPOSE_PROJECT_NAMEauthelia-${SUITE_SLOT} export SUITE_SUBNET10.240.${SUITE_SLOT} export LDAP_ADMIN_PORT$((9090 SUITE_SLOT)) export ENVOY_ADMIN_PORT$((9901 SUITE_SLOT))即槽位为 2 时子网变为10.240.2.0/24。注意带槽位的 shell 刻意不去碰/etc/hosts。原因是该文件是机器级的而其背后的地址只属于某一个网络只能由一个工作树独占。测试本身并不依赖它Chrome 通过--host-resolver-rules解析套件域名Go 客户端在拨号dial时解析域名两者使用同一张来自 internal/suites/hosts.go 的映射表HostResolverRules与ResolveAddr/DialContext。这样/etc/hosts仍指向默认的192.168.240.0/24网络未分槽位的工作树可以继续用上文列出的地址在浏览器中访问而带槽位的套件并行运行不受影响。如果你想在浏览器里访问带槽位的套件直接使用其地址即可例如https://10.240.2.100:8080。并发运行时还有两点共享资源值得注意pnpm store~/.local/share/pnpm/store与Go 模块/构建缓存${GOPATH}会被绑定挂载进每个套件的开发容器。它们并发使用是安全的但会存在竞争。开发模式下每个套件在后端、前端、代理容器上大约占用6 个 CPU 核心与 6 GB 内存外加测试用的一个 Chrome 进程。请据此规划并发套件数量。远程调试所有套件的 Authelia 都以 delve 调试器运行支持远程调试。调试器监听地址为${SUITE_SUBNET}.50:2345未分槽位的工作树即192.168.240.50:2345。连接示例dlv connect 192.168.240.50:2345连接成功后即可像本地调试一样设置断点、查看变量、单步执行 Authelia 后端代码。若套件带槽位运行把地址替换为对应子网的.50地址即可例如10.240.2.50:2345。运行套件测试测试基于chromedriver Selenium驱动真实 Chrome 浏览器完成因此默认会弹出一个 Chrome 窗口。对已运行套件执行测试如果套件已在运行直接执行authelia-scripts suites test命令会检测.suite文件中记录的当前运行套件并只运行与之匹配的测试见 cmd/authelia-scripts/cmd/suites.go。其底层通过go test -count1 -v -json ./internal/suites -run ^(TestSuiteNameSuite)$执行对应测试函数测试超时取套件注册的TestTimeout。无头模式运行为避免弹出的 Chrome 干扰其他工作可用无头模式authelia-scripts suites test --headless该模式通过设置HEADLESSy环境变量实现见 cmd/authelia-scripts/cmd/suites.go。此外测试命令还支持--failfast首个失败即停止与--test pattern只运行匹配的单个测试。对未运行套件执行测试如果套件尚未启动也可以一步到位直接运行指定套件的测试例如HighAvailabilityauthelia-scripts suites test HighAvailability该命令会先自动完成该套件的 setup再运行测试最后执行 teardownwithEnvtrue路径。若想一次运行多个套件可用逗号分隔名称如suites test Standalone,TwoFactor不带任何参数时则会按顺序运行所有套件例如 CI 中的全量集成测试。测试结束后每个套件的结果会以-json格式写入独立的结果文件命名格式见testResultsFileFmt失败时还会调用套件注册的OnError回调如 Standalone 套件的displayAutheliaLogs输出后端与前端日志帮助定位问题。创建新套件创建一个新套件非常简单。以Standalone套件为例它由三部分组成internal/suites/suite_standalone.go— 定义套件的setup 与 teardown 阶段通常使用 docker compose 拉起整套环境同时定义各阶段超时时间。Standalone 套件的完整注册如下GlobalRegistry.Register(standaloneSuiteName, Suite{ SetUp: setup, SetUpTimeout: 5 * time.Minute, OnError: displayAutheliaLogs, OnSetupTimeout: displayAutheliaLogs, TearDown: teardown, TestTimeout: 5 * time.Minute, TearDownTimeout: 2 * time.Minute, Description: This suite is used to test Authelia in a standalone configuration with in-memory sessions and a local sqlite db stored on disk, })注意它的init()函数还会在SuiteTmpPath(authelia/StandaloneSuite)下预写 jwt/session 密钥文件teardown 时删除临时 sqlite 数据库——这体现了SUITE_TMP/SUITE_TMP_PATH在测试过程中的实际用途。internal/suites/suite_standalone_test.go— 定义针对该套件的测试集合以TestStandaloneSuite为前缀的 Go 测试函数。internal/suites/Standalone目录 — 存放套件所需的资源文件compose 覆盖文件、证书、配置等通常会挂载进容器。套件的复杂度可以远超 Standalone例如Kubernetes 套件internal/suites/suite_kubernetes.go会搭建一整套完整的 Kubernetes 生态作为复杂套件的参考范例。新建套件时遵循同样的三步即可编写suite_name.go注册环境生命周期、编写suite_name_test.go编写测试、创建同名资源目录随后套件会自动出现在authelia-scripts suites list中并可通过suites setup name与suites test name驱动。仓库中已内置 20 余个现成套件internal/suites 下的suite_*.go覆盖 LDAP、MySQL/MariaDB/Postgres、OIDC、Traefik/Envoy/HAProxy/Caddy、PAM、多 Cookie 域、网络 ACL、双因素等场景可直接作为编写新套件的模板。小结Integration Suite 是 Authelia 开发与测试体系的基石authelia-scripts suites setup|test|teardown|slot命令族负责环境生命周期与测试执行SUITE_SLOT机制让同一台机器上的多个工作树互不干扰地并发运行/etc/hosts之外的双重域名解析Chrome 的--host-resolver-rules与 Go 的DialContext保证了隔离网络的正确访问而三件套环境定义 测试 资源目录的约定让新增套件的成本降到最低。无论是为修复某个 bug 搭建手动验证环境还是在 CI 中跑全量集成测试理解本文的机制都能让你事半功倍。【免费下载链接】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），仅供参考