SQLPage 0.47.0 常用 CLI 命令与运维实战

SQLPage v0.47.0 命令行与运维全实测：--web-root/--config-file 参数、create-migration 迁移机制、环境变量覆盖、LOG_LEVEL 日志级别、二进制升级替换、SQLite 备份与 systemd 安全加固。

SQLPageSQLPageSQLRustUbuntu 22.04运维2026/10/28

SQLPage 0.47.0 常用 CLI 命令与运维实战

目标：完整梳理 SQLPage v0.47.0 命令行能力——全局参数（--web-root、--config-dir、--config-file）、create-migration 子命令、环境变量覆盖、日志与日志级别、二进制升级替换、SQLite 备份与 systemd 安全加固，每个命令配真实执行回显。运行环境为 Ubuntu 22.04.5 LTS，安装与配置基础见《Ubuntu 22.04 安装 SQLPage 0.47.0 指南》（https://www.quzuo.net/document/BdtuMjKpDGfZ）与《SQLPage 0.47.0 配置详解与参数生效验证》（https://www.quzuo.net/document/Ctizz1tZy2fN）。

一、CLI 全景与全局参数

1.1 帮助与版本

/opt/sqlpage/bin/sqlpage --help

实测输出：

Build data user interfaces entirely in SQL. A web server that takes .sql files and formats the query result using pre-made configurable professional-looking components.

Usage: sqlpage [OPTIONS] [COMMAND]

Commands:
  create-migration  Create a new migration file
  help              Print this message or the help of the given subcommand(s)

Options:
  -w, --web-root <WEB_ROOT>        The directory where the .sql files are located
  -d, --config-dir <CONFIG_DIR>    The directory where the sqlpage.json configuration, the templates, and the migrations are located
  -c, --config-file <CONFIG_FILE>  The path to the configuration file
  -h, --help                       Print help
  -V, --version                    Print version

/opt/sqlpage/bin/sqlpage --version

实测输出：

sqlpage 0.47.0

CLI 结构很轻：服务器本体没有"启动/停止"子命令——运行 sqlpage 即前台启动服务，停止交给进程信号（systemd 场景即 systemctl stop）。

1.2 三个全局参数

参数作用本系列用法
-w, --web-root指定 .sql 页面根目录unit 中 --web-root /opt/sqlpage/www
-d, --config-dir指定配置目录（sqlpage.json、templates、migrations 所在）未显式使用，默认为工作目录下 ./sqlpage
-c, --config-file显式指定配置文件路径（toml/json5/yaml 均可）unit 中 --config-file /opt/sqlpage/conf/sqlpage.toml

三者对应的环境变量分别是 SQLPAGE_WEB_ROOT、SQLPAGE_CONFIGURATION_DIRECTORY 与配置参数本身的大写形式。命令行参数的生效有明确日志佐证（debug 级实测："Setting web root to value from the command line: /opt/sqlpage/www"）。

二、create-migration 与数据库迁移

2.1 子命令用法与实测

/opt/sqlpage/bin/sqlpage create-migration --help

实测输出：

Create a new migration file

Usage: sqlpage create-migration <MIGRATION_NAME>

Arguments:
  <MIGRATION_NAME>  Name of the migration

Options:
  -h, --help  Print help

在安装目录执行（建议先 chown sqlpage:sqlpage 归属运行账号）：

cd /opt/sqlpage
/opt/sqlpage/bin/sqlpage create-migration init_demo_schema

实测输出：

Migration file created: sqlpage/migrations/20261028015639_init_demo_schema.sql

生成的文件只有一行占位注释 -- Write your migration here，文件名格式为 <YYYYMMDDHHMMSS>_<名称>.sql，时间戳前缀决定了执行顺序。填入实际内容（幂等写法）：

-- init_demo_schema：建应用表（幂等）
CREATE TABLE IF NOT EXISTS app_log (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    action TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

2.2 迁移的自动执行与记录

重启服务后迁移自动执行：

systemctl restart sqlpage && sleep 2
journalctl -u sqlpage --since "-20s" --no-pager -o cat | grep -i migration
sqlite3 /opt/sqlpage/data/app.db ".tables"

实测输出：

ts=2026-10-28T01:56:51.568Z level=info msg="Found 1 migrations:" target=sqlpage::webserver::database::migrations
ts=2026-10-28T01:56:51.568Z level=info msg="	[20261028015639] init demo schema" target=sqlpage::webserver::database::migrations
---
_sqlx_migrations  app_log           demo_product

执行记录落在 _sqlx_migrations 表（版本号、描述、安装时间），已执行的迁移不会重复跑。运维要点：迁移只在启动时执行，新增迁移文件必须重启服务；回滚迁移需要自己写反向脚本。

三、环境变量覆盖与前台调试运行

3.1 环境变量覆盖配置文件

所有配置参数都能用同名大写环境变量（可选 SQLPAGE_ 前缀）设置，且实测可覆盖配置文件中的同名项。toml 中 listen_on = "0.0.0.0:8080"，改用环境变量拉起前台实例：

LISTEN_ON=127.0.0.1:9090 timeout 6 /opt/sqlpage/bin/sqlpage \
  --web-root /opt/sqlpage/www --config-file /opt/sqlpage/conf/sqlpage.toml \
  > /tmp/listen.log 2>&1 &
sleep 3 && curl -s -o /dev/null -w "GET 127.0.0.1:9090/ -> HTTP %{http_code}\n" http://127.0.0.1:9090/
grep "started successfully" /tmp/listen.log | head -c 220

实测输出：

GET 127.0.0.1:9090/ -> HTTP 200
ts=2026-10-28T01:57:04.783Z level=info msg=" ✨ SQLPage v0.47.0 started successfully! ✨  View your website at: 🔗 http://127.0.0.1:9090 ...

启动横幅显示监听地址变成了 127.0.0.1:9090，HTTP 200 验证通过——环境变量覆盖 toml 成立。

3.2 前台调试运行模式

排查问题时推荐"前台 + timeout + 日志重定向"模式：timeout 6 sqlpage ... 跑 6 秒自动退出，期间用 curl 复现请求，日志完整落盘。注意 systemd 常驻实例已占用 8080 时，前台实例必须用环境变量或参数换端口，否则报地址绑定失败。

四、日志体系与日志级别

4.1 默认 info 级与访问日志

SQLPage 使用结构化日志（ts=... level=... msg=... target=... 格式）。默认级别即包含访问日志（target 为 sqlpage::access），实测两条典型记录：

ts=2026-10-28T01:51:36.228Z level=warn msg="404 Not Found" target=sqlpage::access http.request.method=GET url.path=/missing.sql client.address=127.0.0.1
ts=2026-10-28T01:54:27.553Z level=info msg="200 OK" target=sqlpage::access http.request.method=GET url.path=/error-demo.sql client.address=127.0.0.1

4.2 LOG_LEVEL=sqlpage=debug 实测

排障时把日志级别调到 debug（官方 configuration.md 推荐的排障手段）：

LOG_LEVEL=sqlpage=debug timeout 6 /opt/sqlpage/bin/sqlpage \
  --web-root /opt/sqlpage/www --config-file /opt/sqlpage/conf/sqlpage.toml \
  > /tmp/debug.log 2>&1 &
sleep 3 && curl -s -o /dev/null http://127.0.0.1:8080/index.sql
wait && grep -c "level=debug" /tmp/debug.log

实测 6 秒窗口内输出 16 条 debug 日志，关键几条：

ts=...Z level=debug msg="No .env file found, using only environment variables and configuration files" target=sqlpage
ts=...Z level=debug msg="Loading configuration from file: /opt/sqlpage/conf/sqlpage.toml" target=sqlpage::app_config
ts=...Z level=debug msg="Setting web root to value from the command line: /opt/sqlpage/www" target=sqlpage::app_config
ts=...Z level=debug msg="Loaded configuration: AppConfig { database_url: \"sqlite:////opt/sqlpage/data/app.db?mode=rwc\", ... listen_on: Some(0.0.0.0:8080), ... environment: Production, site_prefix: \"/\", compress_responses: true, content_security_policy: ContentSecurityPolicyTemplate { template: \"script-src 'self' 'nonce-{NONCE}'\", ... } }" target=sqlpage::app_config

最有价值的是最后一条：SQLPage 把解析后的完整配置（AppConfig）打了出来，配置排查到此为止——每个参数的最终生效值一目了然。官方另有 OpenTelemetry 链路追踪支持（OTEL_EXPORTER_OTLP_ENDPOINT），需要 APM 时再启用。

4.3 journalctl 常用查询

journalctl -u sqlpage -f                          # 实时跟踪
journalctl -u sqlpage --since "-10 min" -o cat    # 最近 10 分钟（去掉前缀，纯日志行）
journalctl -u sqlpage -g "404"                    # 按 grep 模式过滤
journalctl -u sqlpage --since today | grep -c "level=warn"   # 今日告警计数

注意：-g 过滤与 -o cat 组合时可读性最好；访问日志的 client.address、url.path 字段可直接用于统计。

五、升级替换二进制

5.1 标准升级流程（以同版本演练）

SQLPage 的升级就是"换一个二进制文件"。流程四步：下载新包 → 校验 → 停服替换 → 起服验证。以 v0.47.0 演练（升级新版时把 URL/摘要换成目标版本即可）：

cd /tmp/sqlpage-dl
sha256sum sqlpage-linux.tgz
tar xzf sqlpage-linux.tgz sqlpage.bin -O > sqlpage.bin.new
systemctl stop sqlpage
install -m 0755 -o sqlpage -g sqlpage sqlpage.bin.new /opt/sqlpage/bin/sqlpage
systemctl start sqlpage && sleep 2
/opt/sqlpage/bin/sqlpage --version
curl -s -o /dev/null -w "升级后 GET / -> HTTP %{http_code}\n" http://127.0.0.1:8080/

实测输出：

b566a5d609e2894cf7658c5a421828de3a3b0bc993f405713ee2d2513d27ae5c  sqlpage-linux.tgz
sqlpage 0.47.0
升级后 GET / -> HTTP 200
ts=2026-10-28T01:57:34.321Z level=info msg=" ✨ SQLPage v0.47.0 started successfully! ✨ ..."

要点：install 命令一步完成"落盘+权限+属主"，比先解压再 mv 更稳；SHA-256 必须对照新版官方摘要（GitHub API assets[].digest）。配置文件、页面目录、数据库均与二进制解耦，替换二进制不影响数据。

5.2 回滚

保留上一版本二进制（升级前 cp /opt/sqlpage/bin/sqlpage /opt/sqlpage/bin/sqlpage.prev），回滚即反向替换 + 重启，秒级完成。0.x 版本升级前建议先在测试环境核对 CHANGELOG 的行为变化。

六、备份与日常巡检

6.1 SQLite 备份（实测）

数据库为文件型 SQLite 时，用 sqlite3 的在线备份命令（服务运行中执行安全，不用停服）：

sqlite3 /opt/sqlpage/data/app.db ".backup /tmp/app-backup.db"
sqlite3 /opt/sqlpage/data/app.db "VACUUM INTO '/tmp/app-vacuum.db';"
ls -la /tmp/app-backup.db /tmp/app-vacuum.db

实测输出：

-rw-r--r-- 1 root root 24576 Oct 28 01:57 /tmp/app-backup.db
-rw-r--r-- 1 root root 24576 Oct 28 01:57 /tmp/app-vacuum.db

两种方式都得到完整一致性副本；VACUUM INTO 顺带做碎片整理。把命令放进 cron 即可日常备份。使用 PostgreSQL/MySQL 时改用各自的备份工具，SQLPage 侧无需特殊处理。

6.2 日常巡检清单

systemctl is-active sqlpage                                  # 服务状态
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/   # 健康检查（预期 200）
journalctl -u sqlpage --since -24h | grep -c "level=error"    # 近 24h 错误数（预期 0）
systemctl show sqlpage -p MainPID,MemoryCurrent              # 进程与内存

配合监控平台时，HTTP 探活 + journalctl 错误计数即可覆盖绝大多数告警需求；深度指标可启用 OpenTelemetry 上报。

七、systemd 安全加固

官方仓库提供带安全加固的 unit 模板（来源：GitHub 仓库 sqlpage/SQLPage 的 sqlpage.service，查询日期 2026-10-28），生产环境建议合入本系列 unit：

[Service]
Environment="RUST_LOG=info"
Environment="LISTEN_ON=0.0.0.0:80"
AmbientCapabilities=CAP_NET_BIND_SERVICE
Restart=always
RestartSec=10
SyslogIdentifier=sqlpage
NoNewPrivileges=true
ProtectSystem=full
PrivateTmp=true
ProtectControlGroups=true
ProtectKernelModules=true
ProtectKernelTunables=true
ProtectClock=true
ProtectHostname=true
ProtectProc=invisible
LimitNOFILE=65536

解读几个关键项：NoNewPrivileges 禁止提权；ProtectSystem=full 把 /usr、/boot、/etc 挂为只读（注意数据与页面目录需保持可写，本系列在 /opt 下不受影响）；PrivateTmp 隔离临时目录；CAP_NET_BIND_SERVICE 允许非 root 绑定 80 端口——配合 LISTEN_ON=0.0.0.0:80 直接对外服务，无需 Nginx 也能跑在标准端口。日志级别即由 RUST_LOG=info 控制（与 LOG_LEVEL 同类，LOG_LEVEL=sqlpage=debug 更细）。

八、运维排障实录

  1. 前台调试端口冲突：systemd 实例占用 8080 时前台启动报绑定失败。解法：LISTEN_ON=127.0.0.1:9090 错开端口（3.1 节实测），调试完 timeout 自动退出。
  2. 迁移改了不生效：迁移只在启动时执行，新增/修改迁移文件后必须 systemctl restart sqlpage；执行记录查 _sqlx_migrations 表确认。
  3. 想确认配置文件真的被读了吗：info 日志只显示配置目录（"Configuration loaded from /opt/sqlpage/sqlpage"），容易被误判为 toml 未生效；LOG_LEVEL=sqlpage=debug 可见 "Loading configuration from file: ..." 与完整 AppConfig 转储（4.2 节实测）。
  4. "错误页怎么不报错"：SQLite 里 SELECT 1/0 返回 NULL 而非报错，压测错误处理时应使用引用不存在的表等真实错误；生产环境（environment = "production"）错误统一返回 HTTP 500 与通用提示。
  5. 升级后版本没变：确认替换的是实际运行路径（systemctl cat sqlpage 核对 ExecStart），并用 systemctl restart（而非 start）确保旧进程退出；多实例部署需逐台替换。

至此本系列四篇完结：选型判断看《SQLPage 0.47.0 介绍与选型指南》（https://www.quzuo.net/document/qeGaJyffJQTk），落地路径按安装 → 配置 → 本篇运维的顺序推进。