Domain Locker 常用 CLI 命令详解

Domain Locker v0.3.5 命令行运维实测：npm scripts 全景（build/dev/typecheck/test:server 真机回显）、生产进程管理与 systemd、pg_dump 与 SQLite 在线备份恢复演练、鉴权与域名台账/作业触发 API 实测（RDAP 真实采集 6.4s）、日志排查与 pkill 误杀等真实踩坑（2026-10-28）。

Domain LockerCLI命令运维Nodejs2026/10/28

Domain Locker 常用 CLI 命令详解：构建、运维、备份恢复与 API 实测

本文命令全部在 Ubuntu 22.04.5 + Node.js v22.23.4 + PostgreSQL 14.24 真机实测（实测日期 2026-10-28），组件版本 Domain Locker v0.3.5，应用目录 /root/domain-locker，服务端口 8147。输入输出逐行照抄实测回显；示例口令 q1w2e3r4。部署与参数细节见 《Domain Locker Ubuntu 22.04 安装部署指南》、《Domain Locker 配置参数详解》。

1. npm scripts 全景与适用场景

v0.3.5 的 package.json 定义了如下 scripts（摘自源码，# 后为实测备注）：

命令作用实测情况
npm run dev开发服务器（Analog/Vite dev，默认 5173）✅ 起服务、HTTP 200
npm run build生产构建，产物 dist/analog/server/index.mjs✅
npm start等价 node dist/analog/server/index.mjs，起生产服务✅（以 node 直启实测）
npm run typecheck应用+服务端两段 TypeScript 类型检查✅ 退出码 0
npm run test:serverVitest 服务端测试✅ 179 通过
npm test前端组件测试📖 未跑（依赖浏览器环境较多）
npm run lint / format / format:checkESLint / Prettier📖 未跑
npm run hold-my-beerformat+typecheck+lint 三连（作者趣味命名）📖 未跑
npm run migrate:pg-to-sqlitePostgreSQL 数据迁回 SQLite 的脚本📖 未跑

2. 构建与启动命令

2.1 生产构建

# cd /root/domain-locker
# NODE_OPTIONS=--max-old-space-size=4096 npm run build
Prerendering static pages...
Building Server...


The '@analogjs/platform' server has been successfully built.
# du -sh dist
82M     dist

2.2 启动与进程管理

生产入口只有一句话（npm start 与之等价）：

# cd /root/domain-locker
# node dist/analog/server/index.mjs
🔵 [env] Read 9 settings from /root/domain-locker/.env
🔵 [database] Using Postgres at localhost/domain_locker
🔵 [scheduler] Scheduled domain-monitor every 15 minutes
...
Listening on http://[::]:8147

后台常驻、查状态、停服务：

# nohup node dist/analog/server/index.mjs > /var/log/domain-locker.log 2>&1 &
# ps -ef | grep "node dist" | grep -v grep
root        7507       1  0 05:12 ?        00:00:00 node dist/analog/server/index.mjs
# ss -ltn | grep 8147
LISTEN 0      511                *:8147             *:*
# pkill -f "^node dist"        # 注意：模式要锚定行首，否则会误杀包含该字符串的当前 shell

⚠️ 排障实录：pkill -f "dist/analog" 这类不锚定的模式会把调用它的 shell 自身一并杀掉（命令行里同样含该字符串），表现为命令突然以 143（SIGTERM）退出。用 pkill -f "^node dist" 锚定进程名开头即可。长期运行建议直接用 systemd 单元（配置见 B 篇 7.2 节）。

2.3 开发服务器（调参/调试用）

# npm run dev
  ➜  Local:   http://localhost:5173/
🔵 [database] Database already up to date
# curl -s -o /dev/null -w "dev-server HTTP %{http_code}\n" http://localhost:5173/
dev-server HTTP 200

dev 服务器复用同一套 .env 与数据库，改配置热生效，调 DL_* 参数时比反复构建快得多；生产禁用。

3. 类型检查与测试

3.1 typecheck

# npm run typecheck

> domain-locker@0.3.5 typecheck
> npm run typecheck:app && npm run typecheck:server

> domain-locker@0.3.5 typecheck:app
> tsc --noEmit -p tsconfig.app.json

> domain-locker@0.3.5 typecheck:server
> tsc --noEmit -p tsconfig.server.json

（退出码 0，无输出即通过）

改完模板/服务端代码、升级依赖后先跑它，比构建快得多。

3.2 服务端测试

# npm run test:server
 Test Files  1 failed | 17 passed | 3 skipped (21)
      Tests  179 passed | 27 skipped (206)
   Start at  05:15:28
   Duration  125.11s (transform 303ms, setup 25ms, collect 454ms, tests 124.21s, environment 0ms, prepare 259ms)

⚠️ 排障实录（两条都实测踩过）：

  1. 唯一失败的测试文件是 test/api/dev-server.spec.ts——它要求一个在跑的 dev 服务器，生产机直接跑必然失败，属预期现象；其余 17 个文件 179 条用例全绿。
  2. 在项目目录之外跑会报 npm error enoent Could not read package.json: Error: ENOENT: no such file or directory, open '/root/package.json'（退出码 254）——npm scripts 必须在 /root/domain-locker 目录下执行。

4. 数据库备份与恢复

4.1 PostgreSQL 模式：pg_dump / psql

备份（逻辑全量）：

# PGPASSWORD=q1w2e3r4 pg_dump -h localhost -U domainlocker domain_locker > /root/dl-backup-$(date +%F).sql
# wc -l /root/dl-backup-2026-10-28.sql
1233 /root/dl-backup-2026-10-28.sql
# grep -c "CREATE TABLE" /root/dl-backup-2026-10-28.sql
23

恢复演练（实测新建空库灌入并核对数据）：

# PGPASSWORD=q1w2e3r4 psql -h localhost -U postgres -c "CREATE DATABASE domain_locker_restore OWNER domainlocker;"
CREATE DATABASE
# PGPASSWORD=q1w2e3r4 psql -h localhost -U domainlocker -d domain_locker_restore -f /root/dl-backup-2026-10-28.sql | tail -3
ALTER TABLE
ALTER TABLE
ALTER TABLE
# PGPASSWORD=q1w2e3r4 psql -h localhost -U domainlocker -d domain_locker_restore -c "SELECT domain_name FROM domains;"
 domain_name
-------------
 example.com
(1 row)

建议 crontab 每日一份 pg_dump，保留 7~30 天滚动；恢复目标库的用户与属主要与 .env 的 DL_PG_USER/DL_PG_NAME 一致，应用起来即可直连。

4.2 SQLite 模式：在线备份

SQLite 在运行期直接 cp 数据文件会漏 WAL，用 .backup 命令做一致性快照（实测）：

# cd /root/domain-locker
# sqlite3 data/domain-locker.db ".backup /root/sqlite-backup-test.db"
# ls -la /root/sqlite-backup-test.db
-rw-r--r-- 1 root root 319488 Oct 28 05:17 /root/sqlite-backup-test.db
# sqlite3 /root/sqlite-backup-test.db ".tables"
billing                   domains                   ssl_certificates
dns_records               hosts                     sub_domains
domain_costings           ip_addresses              tags
domain_hosts              job_runs                  uptime
domain_links              notification_preferences  user_info

恢复 SQLite = 停进程 → 用备份文件覆盖 DL_SQLITE_PATH 指向的库文件 → 起进程。

4.3 应用层数据导出（补充手段）

无需登录数据库的应用内导出接口（支持 json/csv 等格式，见 GET /api/v1/export）：

# curl -s "http://localhost:8147/api/v1/export?format=json" | head -c 200
[{"domain_name":"example.com","expiry_date":"","registration_date":"","updated_date":"","notes":"lab test domain","registrar_name":"Example Registrar",...

适合给用户导出或迁移到其他工具，不能替代数据库级备份（不含 uptime 明细等全量表）。

5. API 运维命令实测

以下命令均以 DL_AUTH_PASSWORD=q1w2e3r4、DL_API_KEY=dl-key-2026-test 的实机为基准。

5.1 鉴权

# curl -s http://localhost:8147/api/v1/auth/status
{"authRequired":true,"authenticated":false}
# curl -s -c /tmp/dl-cookie.txt -X POST http://localhost:8147/api/v1/auth/login \
  -H "Content-Type: application/json" -d '{"password":"q1w2e3r4"}'
{"authenticated":true}

拿到 Cookie 后的请求带 -b /tmp/dl-cookie.txt；脚本/定时任务更推荐 -H "x-api-key: dl-key-2026-test"。

5.2 域名台账

# 列出全部域名
# curl -s -H "x-api-key: dl-key-2026-test" http://localhost:8147/api/v1/domains
[{"id":"8fbdc43e-...","domain_name":"example.com","expiry_date":null,...}]
# 新增域名
# curl -s -X POST http://localhost:8147/api/v1/domains \
  -H "Content-Type: application/json" \
  -d '{"domain":{"domain_name":"example.com","registrar":"Example Registrar"},"tags":["lab"]}'
{"id":"8fbdc43e-9fa2-4f0d-adb3-4016338b8ddc",...}
HTTP 200

5.3 手动触发定时作业

v0.3.x 内置调度器，但迁移/重跑/外部 cron 场景可手动触发。四个作业端点：/domain-monitor、/domain-updater、/expiration-reminders、/cleanup-monitor-data，仅 selfHosted 模式开放、需 API Key 或会话：

# curl -s -X POST -H "x-api-key: dl-key-2026-test" --max-time 90 http://localhost:8147/domain-updater
{"job":"domain-updater","ran":true,"result":{"checked":1,"changed":1,"results":[{"domain":"example.com","changes":["Expiry Date","Updated Date","Registration Date","Registrar","Status+: clientdeleteprohibited","Status+: clienttransferprohibited","Status+: clientupdateprohibited","SSL created","DNS TXT+","DNS TXT+","DNS NS+","DNS NS+","DNS MX+","Host"]}]},"durationMs":6381}

返回体自带 durationMs 与逐域名 changes 清单，可直接用于巡检脚本。作业执行细节同步落在应用日志（🟢 [whois] Got WHOIS data via RDAP ... 等）。

5.4 配置下发端点

# curl -s http://localhost:8147/api/env-var
{"envType":"selfHosted",...}          # 仅 selfHosted 模式可用，dev 模式返回 403 提示

6. 日志与排查命令

场景命令
看实时日志tail -f /var/log/domain-locker.log（systemd 部署则 journalctl -u domain-locker -f）
过滤错误/告警grep -E "🔴|🟡" /var/log/domain-locker.log（🟡 告警、🔴 错误、🟢 成功、🔵 信息）
确认 .env 已加载启动日志首行 🔵 [env] Read N settings from ... 的 N
确认数据库模式grep "\[database\]" 日志，SQLite/Postgres 二选一
确认调度器状态grep "\[scheduler\]" 日志，被禁用时出现 disabled 行
npm 自身报错日志ls ~/.npm/_logs/（如 enoent 类错误的 debug-0.log）

7. 常用命令速查

# 构建启动类
npm ci --no-audit --no-fund
NODE_OPTIONS=--max-old-space-size=4096 npm run build
node dist/analog/server/index.mjs            # 或 npm start
npm run dev                                  # 开发调试（5173）

# 质量类
npm run typecheck
npm run test:server

# 备份恢复类
PGPASSWORD=<口令> pg_dump -h localhost -U domainlocker domain_locker > backup.sql
PGPASSWORD=<口令> psql -h localhost -U domainlocker -d <库> -f backup.sql
sqlite3 data/domain-locker.db ".backup /backup/path.db"

# API 运维类
curl -s -H "x-api-key: $DL_API_KEY" http://localhost:8147/api/v1/domains
curl -s -X POST -H "x-api-key: $DL_API_KEY" http://localhost:8147/domain-updater
curl -s -X POST -H "x-api-key: $DL_API_KEY" http://localhost:8147/expiration-reminders

相关阅读