Domain Locker 配置参数详解：.env 全参数逐项生效验证

本文在 Ubuntu 22.04.5 + Node.js v22.23.4 + PostgreSQL 14.24 上对 Domain Locker v0.3.5 做逐项配置实测（实测日期 2026-10-28）。每项参数标注验证状态：✅ 实测（本文真机回显）、📖 文档核实（来自官方文档/源码，未单独触发验证）。部署过程见 《Domain Locker Ubuntu 22.04 安装部署指南》。

1. .env 的加载机制与优先级

Domain Locker 从两处读取配置（来源：官方文档《Environmental Variables》，查询日期 2026-10-28）：

• 运行时变量：进程环境变量，或应用根目录下与 dist/ 同级的 .env 文件；
• 构建时变量：执行 npm run build 时已存在的 .env，其中部分值会被烘焙进前端产物。

优先级：运行时 > 构建时 > 兜底默认值。服务端只把 src/server/utils/client-env.ts 白名单内的变量下发给浏览器（经 /api/env-var 端点），DL_PG_PASSWORD、DL_AUTH_PASSWORD 等敏感项永不进入前端。

两个实测结论：

1. 改 .env 必须重启进程才生效（官方文档原话 "You have to restart the app for changes to env vars to take affect"）。
2. 每次启动第一行日志即回显加载了几个配置项，可用于快速确认 .env 是否被读到：

🔵 [env] Read 2 settings from /root/domain-locker/.env

浏览器侧配置下发端点有环境门禁，实测 dev 模式下访问直接被拒：

# curl -s http://localhost:8147/api/env-var
{"error":true,"message":"This endpoint is only available for selfHosted environment."}

2. DL_ENV_TYPE：运行模式（✅ 实测）

四种取值（来源：官方文档；managed 仅官方托管实例使用）：

DL_ENV_TYPE=dev + Supabase 凭据的实测（凭据取自仓库 .env.sample 的公开 anon key）：

🔵 [env] Read 4 settings from /root/domain-locker/.env
Listening on http://[::]:8147

对比 selfHosted 模式：没有 database/scheduler/migrations 日志段——dev 模式下数据面走 Supabase（浏览器直连），本地 Nitro 服务只承担页面与代理。此时本地 v1 API 被门禁：

# curl -s http://localhost:8147/api/v1/auth/status
{
  "error": true,
  "url": "http://localhost:8147/api/v1/auth/status",
  "statusCode": 403,
  "statusMessage": "Server Error",
  "message": "Server Error"
}

选型结论：自托管一律 DL_ENV_TYPE=selfHosted；dev 仅用于参与项目开发且愿意连官方共享 dev 库的场景，官方明确标注 NOT suitable for production。

3. 端口与地址

4. 数据库参数

4.1 SQLite（默认，✅ 实测）

未设置任何 DL_PG_* 时自动使用 SQLite，零配置：

🔵 [database] Using SQLite at /root/domain-locker/data/domain-locker.db

自定义路径（✅ 实测 DL_SQLITE_PATH=/root/dl-data/custom-locker.db）：

🔵 [database] Using SQLite at /root/dl-data/custom-locker.db
# ls -la /root/dl-data/
-rw-r--r-- 1 root root   4096 Oct 28 05:11 custom-locker.db
-rw-r--r-- 1 root root  32768 Oct 28 05:11 custom-locker.db-shm
-rw-r--r-- 1 root root 704552 Oct 28 05:11 custom-locker.db-wal

可见 SQLite 以 WAL 模式运行（-shm/-wal 伴随文件）。备份时务必连同 -wal 文件或使用 sqlite3 在线备份，命令见 《Domain Locker 常用 CLI 命令详解》。

4.2 PostgreSQL（✅ 实测）

五个变量必须成组配置：DL_PG_HOST、DL_PG_PORT、DL_PG_USER、DL_PG_PASSWORD、DL_PG_NAME。

只配一部分时的真实行为（✅ 实测仅设 DL_PG_HOST）：

🟡 [database] Postgres is only partly configured, so SQLite is being used instead. Missing: DL_PG_USER, DL_PG_PASSWORD, DL_PG_NAME
🔵 [database] Using SQLite at /root/domain-locker/data/domain-locker.db

即静默回退 SQLite（黄色告警），不会启动失败——排查"明明配了 PG 为什么数据还在 SQLite"时先看这行日志。完整配置后：

🔵 [database] Using Postgres at localhost/domain_locker

schema 应用与迁移由应用启动时自动完成；若用官方 db/setup-postgres.sh 建库，注意脚本以 DL_PG_PASSWORD 连接 postgres 超级用户的坑（实测与解法见 B 篇 6.2 节）。

4.3 Supabase 连接（✅ 门禁实测）

SUPABASE_URL + SUPABASE_ANON_KEY 只在 DL_ENV_TYPE=dev / managed 场景生效（实测行为见第 2 节：本地数据库与调度器段落消失、v1 API 返回 403）。配套变量 DL_SUPABASE_PROJECT 为项目 ID（📖 文档核实）。官方对自托管用户的建议（来源：官方文档《Supabase Setup》，查询日期 2026-10-28）："Where possible, we recommend self-hosted users to use SQLite or Postgres instead"——Supabase 栈仅推荐给复刻官方托管版的团队，其配置/迁移/Edge Functions 独立维护在 Lissy93/dl-sb-iac 仓库。

5. 鉴权参数（✅ 全链路实测）

未设置口令时的启动告警（真实回显）：

🟡 [security] No DL_AUTH_PASSWORD or DL_API_KEY is set, so anyone who can reach this instance can read your domains and trigger the scheduled jobs

设置 DL_AUTH_PASSWORD=q1w2e3r4、DL_API_KEY=dl-key-2026-test 后，告警消失，鉴权链路逐条实测：

# curl -s http://localhost:8147/api/v1/auth/status
{"authRequired":true,"authenticated":false}

# 无凭据访问业务 API → 401
# curl -s -w "\nHTTP %{http_code}\n" http://localhost:8147/api/v1/domains
{
  "error": true,
  "url": "http://localhost:8147/api/v1/domains",
  "statusCode": 401,
  ...
}
HTTP 401

# 错误口令 → 401
# curl -s -w "\nHTTP %{http_code}\n" -X POST http://localhost:8147/api/v1/auth/login \
  -H "Content-Type: application/json" -d '{"password":"wrongpass"}'
{"error":{"code":"unauthorized","message":"Incorrect password"}}
HTTP 401

# 正确口令 → 200 并下发 dl_session Cookie
# curl -s -c /tmp/dl-cookie.txt -w "\nHTTP %{http_code}\n" -X POST http://localhost:8147/api/v1/auth/login \
  -H "Content-Type: application/json" -d '{"password":"q1w2e3r4"}'
{"authenticated":true}
HTTP 200

# Cookie 会话与 X-API-Key 均可通过
# curl -s -b /tmp/dl-cookie.txt http://localhost:8147/api/v1/domains
[]
# curl -s -H "x-api-key: dl-key-2026-test" http://localhost:8147/api/v1/domains
[]

要点：会话 Cookie 30 天有效；作业触发端点（如 /domain-updater）凭口令或 API Key 任一即可调用，因此只想保护 cron 端点时可以只配 DL_API_KEY 不配口令。

6. 调度器与监控开关（✅ 实测）

v0.3.0 起应用内置四类定时作业，默认间隔（启动日志实测）：

🔵 [scheduler] Scheduled domain-monitor every 15 minutes
🔵 [scheduler] Scheduled domain-updater every 1440 minutes
🔵 [scheduler] Scheduled expiration-reminders every 1440 minutes
🔵 [scheduler] Scheduled cleanup-monitor-data every 10080 minutes

7. WHOIS 采集参数

8. 数据保留参数（📖 文档核实）

以上四项在 v0.3.4 引入（来源：GitHub Releases v0.3.4 说明 "feat: data retention policy for self-hosted"，查询日期 2026-10-28）。数据库膨胀或合规要求有限留存时配置；本文未构造长周期数据逐项验证清理效果。

9. 通知与第三方集成（📖 文档核实）

通知通道均依赖外部服务，本文未逐一联通验证；通道行为与自托管通知机制另见官方文档《Notifications for Self-Hosted》。

10. 其他参数

11. 全参数速查表

12. 未逐项实测清单（诚实声明）

以下参数因依赖外部服务或长周期数据，本文仅做文档与源码核实，未触发验证：保留策略四项的实际清理动作、通知三通道的端到端推送、Turnstile/GlitchTip/Plausible 集成效果、DL_BASE_URL 的 sitemap 行为、DL_MONITOR_CONCURRENCY/DL_UPDATER_BATCH_SIZE 的并发上限压测、demo/managed 两种模式的完整行为。如需这些项的实测结论，应在具备对应外部条件的环境另行验证。

相关阅读

• 《Domain Locker 介绍与选型指南》：定位与技术架构
• 《Domain Locker Ubuntu 22.04 安装部署指南》：安装、PostgreSQL 切换与部署排障
• 《Domain Locker 常用 CLI 命令详解》：进程管理、备份恢复与 API 实测
• 《Uptime Kuma 配置参数详解》：拨测侧同类工具的配置参考