Aptabase 配置参数详解

目标：给出 Aptabase 自托管实例的全部环境变量清单、逐项含义、默认行为与实测验证方法，并提供两套可直接套用的生产配置模板。全部内容基于 Ubuntu 22.04 + Aptabase main 镜像（2026-10-30 拉取）实测，配置全貌以官方源码 src/Features/EnvSettings.cs 为准。

一、环境信息

• 操作系统：Ubuntu 22.04 LTS（x86_64）
• Aptabase：ghcr.io/aptabase/aptabase:main（main 滚动镜像，2026-10-30 实测；程序集版本 1.0.0，无语义化发布版本）
• 配置载体：仅环境变量，无配置文件（docker compose 部署形态，见 《Aptabase Docker Compose 部署指南》）
• 配置定义源码：https://github.com/aptabase/aptabase/blob/main/src/Features/EnvSettings.cs（查询日期 2026-10-30）
• 依赖库：PostgreSQL 15-alpine、ClickHouse 23.8.4.69-alpine（官方编排锁定组合）

二、前置条件

1. 已按部署指南完成三服务编排并可访问控制台（本文所有修改动作都在既有部署上做增量调整）；
2. 熟悉 docker compose 环境变量的注入方式（environment: 段）；
3. 明确两个连接串的凭据来源：应用连接 PostgreSQL/ClickHouse 所用用户名口令，必须与两个依赖库容器自己的 POSTGRES_*/CLICKHOUSE_* 变量一致；
4. 如需配 SMTP，准备好邮箱服务商的 SMTP 地址、端口与授权码。

三、参数查看与修改方式

3.1 查看当前生效配置

Aptabase 没有配置回显接口，通过编排文件与容器实际环境双向确认：

cd /opt/aptabase
docker compose config | grep -A 8 'environment'   # 查看编排最终注入值（含合并与转义结果）
docker exec aptabase-main-app env | grep -E 'BASE_URL|DATABASE_URL|CLICKHOUSE_URL|SMTP_|OAUTH_'   # 查看容器实际生效值

实测输出（env 部分，密码为示例部署值）：

BASE_URL=http://192.168.1.200:8000
AUTH_SECRET=c4rI4x8kz5DgKJ1is5Eiu9bNncSQ6ROD
DATABASE_URL=Server=aptabase_db;Port=5432;User Id=aptabase;Password=q1w2e3r4;Database=aptabase
CLICKHOUSE_URL=Host=aptabase_events_db;Port=8123;Username=aptabase;Password=q1w2e3r4

3.2 修改配置

全部变量统一在 docker-compose.yml 的 environment: 段修改，然后重建容器：

vim docker-compose.yml       # 修改 environment 段
docker compose up -d         # 变更生效（环境变量变化会触发应用容器重建）

⚠️ 注意：docker compose restart 不会重读编排文件中的环境变量，改完配置必须用 up -d 重建。

3.3 修改结果的验证

• 启动层面：必填项缺失时应用启动即失败，日志直接抛出缺失变量名。实测把 BASE_URL 去掉后启动（docker run --rm ghcr.io/aptabase/aptabase:main）：

Exception: Missing BASE_URL environment variable

• 行为层面：各参数的行为验证方法在第五章逐项给出（如 BASE_URL 看激活链接域名、SMTP 看日志邮件走向）。

四、参数总览

按用途分组的全量清单（依据 EnvSettings.cs Load() 逻辑，查询日期 2026-10-30）：

💡 技术拓展：Aptabase 的数据库连接参数是「.NET 连接串」格式（分号键值对），而非多数工具的 URL 格式（postgres://user:pass@host/db）。两者常见于不同生态——.NET 系（Entity Framework、Npgsql）惯用连接串；Node/Python 系惯用 URL。自托管无需二选一：Aptabase 只认连接串，如果手上只有 URL 形式的参数（云数据库控制台常给 URL），需手动拆出 host/port/user/password/database 重拼为连接串。Aptabase 实际采用连接串格式，因其服务端为 .NET 技术栈。

五、核心参数分类详解

5.1 站点基准 BASE_URL

作用：全站链接基准——注册激活链接、登录魔法链接、OAuth 回调地址都由它拼接；服务端按它判断请求来源。

规则（源码 NormalizeBaseUrl，实测验证）：

• 必须是绝对 URL，服务端会去除首尾空白与末尾斜杠；
• 不带协议时自动补 https://（因此内网 HTTP 部署必须显式写 http://IP:端口，否则被当成 https 域名）；
• 拼不出合法绝对 URL 时启动失败：Exception: BASE_URL must not be empty / BASE_URL must be an absolute URL。

验证：配置 BASE_URL=http://192.168.1.200:8000 后，注册时日志中的激活链接域名端口与之完全一致（实测取自应用日志）：

http://192.168.1.200:8000/api/_auth/continue?token=eyJhbGciOiJIUzI1NiIsInR5cCI6...

⚠️ 注意：BASE_URL 改变后，历史激活/登录链接的域名不变（链接生成于发送时刻），以浏览器当时打开的为准。生产环境走 TLS 反代时必须写成 https://analytics.yourdomain.com，否则会触发「登录成功但会话保持失败」的 Secure Cookie 问题（见部署指南常见问题 Q1）。

5.2 令牌签名密钥 AUTH_SECRET

作用：注册/登录 JWT 的签名密钥。激活链接、登录链接中的 token 均是服务端用 AUTH_SECRET 签发的 HS256 JWT（实测解码 payload 含 "iss":"aptabase-sh"，-sh 即 Self Hosted 标识）。

风险与要求：

• 泄露等于可伪造任意用户的登录链接，必须用强随机值（openssl rand -hex 24）；
• 更换后所有已签发链接立即失效（含未点击的激活链接），已登录会话随 JWT 校验失败而失效，需重新登录；
• 官方示例值 c4rI4x8kz5DgKJ1is5Eiu9bNncSQ6ROD 仅作样例，禁止照抄上生产。

验证：更换后用旧链接访问应回到未登录状态，重新走一次 signin 流程恢复正常。

5.3 数据库连接 DATABASE_URL 与 CLICKHOUSE_URL

PostgreSQL（元数据）：

Server=aptabase_db;Port=5432;User Id=aptabase;Password=q1w2e3r4;Database=aptabase

• Server：主机名，Compose 内写服务名（同网络内 DNS 解析）；外部托管数据库则写 IP/域名；
• Port：PostgreSQL 默认 5432；
• User Id / Password：与依赖库容器的 POSTGRES_USER/POSTGRES_PASSWORD 保持一致；
• Database：首次启动自动创建并执行迁移（FluentMigrator）。

ClickHouse（事件库）：

Host=aptabase_events_db;Port=8123;Username=aptabase;Password=q1w2e3r4

• Port 必须是 8123（HTTP 接口端口），不是 9000 原生协议端口——应用走 HTTP 客户端访问 ClickHouse；
• Username/Password 与依赖库容器的 CLICKHOUSE_USER/CLICKHOUSE_PASSWORD 一致。

别名机制：两串都支持 ASP.NET 标准的 ConnectionStrings__postgresdb / ConnectionStrings__clickhousedb 写法替代（源码 GetOrNull 逻辑），PaaS 平台注入连接串时有用；Compose 部署直接用 DATABASE_URL/CLICKHOUSE_URL 即可。

验证：应用启动日志无数据库连接异常、面板能出数即为连通。实测断开验证——把 CLICKHOUSE_URL 密码改错并重建后，事件上报返回 200 但面板持续为 0，应用日志出现 ClickHouse 连接错误；改回正确值并等待后台刷新后数据恢复，上报成功不代表事件已入库（中间隔着应用内缓冲，见部署指南常见问题 Q2）。

5.4 邮件组（SMTP_*）

默认行为（未配置时，实测）：所有邮件改由 LoggerEmailClient 写入应用日志，注册激活邮件模板名为 Register，登录邮件为登录链接——这是内网/离线环境完成账号激活的官方默认路径（官方 self-hosting README 明示该行为）：

"Sending email to 'admin@aptabase.local' with template 'Register' and '[name, admin], [url, http://192.168.1.200:8000/api/_auth/continue?token=...]'"

验证：配置 SMTP 后注册一个测试账号，观察应用日志不再出现 Sending email 行（走真实 SMTP 后由外部邮箱服务投递），目标邮箱能收到激活邮件。

5.5 OAuth 登录组（OAUTH_GITHUB_* / OAUTH_GOOGLE_*）

• OAUTH_GITHUB_CLIENT_ID / OAUTH_GITHUB_CLIENT_SECRET：GitHub OAuth App 凭据；
• OAUTH_GOOGLE_CLIENT_ID / OAUTH_GOOGLE_CLIENT_SECRET：Google OAuth 凭据；
• 回调地址规则（源码注释明示）：GitHub 回调填 {BASE_URL}/api/_auth/github/callback，Google 回调填 {BASE_URL}/api/_auth/google/callback——BASE_URL 变更后必须同步修改 OAuth 应用里的回调配置；
• 启用条件：配齐任意一对即启用对应登录按钮（源码注释「OAuth will be enabled if at least one pair is configured」）；
• 配置后在控制台登录页可见对应第三方登录入口，GET /api/_auth/providers 会返回可用登录方式。

5.6 云托管专用组（自托管留空）

5.7 行为开关

• ASPNETCORE_ENVIRONMENT：设为 Development 时应用进入开发态（Region 强制 DEV、计费启用派生逻辑变化），生产不要设置，保持默认 Production（实测启动日志 Hosting environment: Production）；
• ERROR_QUOTA_ENABLED：错误上报配额开关，默认 false（源码注释标注 Not yet enabled，属预留开关），自托管保持默认。

5.8 依赖库环境变量（PostgreSQL / ClickHouse 容器）

这两个库的变量只影响库容器自身初始化，但必须与应用连接串呼应：

• POSTGRES_USER / POSTGRES_PASSWORD：首次初始化建库建用户；卷已初始化后改名无效（需清卷重建）；
• CLICKHOUSE_USER / CLICKHOUSE_PASSWORD：ClickHouse 用户凭据，同样在首次初始化时生效。

六、生产配置模板

模板 A：公网 HTTPS（Nginx 反代终结 TLS，50 人团队、每天百万级以内事件，8GB 内存/100GB SSD）

    environment:
      BASE_URL: https://analytics.yourdomain.com      # 与反代域名一致，必须 https
      AUTH_SECRET: <openssl rand -hex 24 生成>
      DATABASE_URL: Server=aptabase_db;Port=5432;User Id=aptabase;Password=<强口令>;Database=aptabase
      CLICKHOUSE_URL: Host=aptabase_events_db;Port=8123;Username=aptabase;Password=<强口令>
      SMTP_HOST: smtp.exmail.qq.com                   # 邮件走真实 SMTP
      SMTP_PORT: 587
      SMTP_USERNAME: notify@yourdomain.com
      SMTP_PASSWORD: <服务商授权码>
      SMTP_FROM_ADDRESS: notify@yourdomain.com

要点：BASE_URL 必须 https（Secure Cookie 生效的前提）；SMTP 必配（激活/登录不再依赖日志）；数据库口令与示例区分开并定期轮换。

模板 B：内网隔离（无外网出口，实验/内部工具，4GB 内存）

    environment:
      BASE_URL: http://10.0.0.5:8000                  # 显式带 http:// 协议与端口
      AUTH_SECRET: <内网生成的随机串>
      DATABASE_URL: Server=aptabase_db;Port=5432;User Id=aptabase;Password=<强口令>;Database=aptabase
      CLICKHOUSE_URL: Host=aptabase_events_db;Port=8123;Username=aptabase;Password=<强口令>

要点：内网 http 场景接受 Secure Cookie 限制（接口调用可携带 Cookie 头，浏览器交互登录受影响）；SMTP 留空走日志邮件；OAuth 组留空（回调域名不可达）。适用「内部工具埋点、不上公网」的场景。

七、常见问题

Q1：改了环境变量但不生效？ 用 docker compose up -d 重建而非 restart（restart 不重读编排文件的环境变量）。重建后用 docker exec aptabase-main-app env 确认容器内实际值。

Q2：启动报 Missing 变量？ 必填项为 BASE_URL、AUTH_SECRET、DATABASE_URL（任一缺失启动即抛 Exception: Missing <变量名> environment variable）。按第四章总览补齐。

Q3：SMTP 配了还是收不到邮件？ 依次检查：SMTP_PORT 是否整数（非数字按 0 处理等于未启用）；服务商是否要求授权码而非登录密码；从日志确认发信是否有异常。若只是内网实验，直接接受「邮件进日志」的默认行为即可。

Q4：OAuth 按钮没出现？ Client ID 与 Secret 必须成对配置才启用；且回调地址必须与 OAuth 应用后台登记的 {BASE_URL}/api/_auth/github|google/callback 完全一致。

Q5：能把 Region 设成 EU/US 提升「合规形象」吗？ 不能。REGION 是云托管模式开关，自托管设置后会激活托管云的计费/管道逻辑，造成未定义行为。自托管保持不设（默认 SH）。

八、参考链接

1. 环境变量定义源码（本篇配置全貌依据）：https://github.com/aptabase/aptabase/blob/main/src/Features/EnvSettings.cs
2. 官方自托管指南：https://github.com/aptabase/self-hosting
3. 部署过程与环境变量初值：《Aptabase Docker Compose 部署指南》
4. 接口行为与事件上报协议实测：《Aptabase API 使用详解》
5. 项目定位与选型背景：《Aptabase 介绍与选型指南》