SQLPage 0.47.0 配置详解与参数生效验证

目标：以 SQLPage v0.47.0 为基线，讲清 sqlpage.toml 配置体系（文件格式、查找位置、环境变量规则），并对监听、数据库、运行环境、压缩、CSP、站点前缀等核心参数做逐项生效验证——每一项都给出改动、命令与实测回显。参数默认值以官方 configuration.md 为准（查询日期 2026-10-28）。安装基础见《Ubuntu 22.04 安装 SQLPage 0.47.0 指南》（https://www.quzuo.net/document/BdtuMjKpDGfZ），选型背景见《SQLPage 0.47.0 介绍与选型指南》（https://www.quzuo.net/document/qeGaJyffJQTk）。

一、配置体系总览

1.1 三种配置文件格式与查找位置

SQLPage 支持三种配置文件格式：.json5、.toml、.yaml（来源：官方 configuration.md，2026-10-28）。文件放在配置目录中，配置目录默认是工作目录下的 ./sqlpage/，可通过命令行参数 --config-dir 或环境变量 SQLPAGE_CONFIGURATION_DIRECTORY 修改。

本系列采用更明确的组织方式：配置文件统一放 /opt/sqlpage/conf/sqlpage.toml，由 systemd 的 ExecStart 通过 --config-file 显式传入：

ExecStart=/opt/sqlpage/bin/sqlpage --web-root /opt/sqlpage/www --config-file /opt/sqlpage/conf/sqlpage.toml

有一个容易误读的现象必须先说清：即使用了 --config-file，info 级启动日志仍显示 Configuration loaded from /opt/sqlpage/sqlpage（它显示的是配置目录而非文件路径）。配置文件是否真的被读取，可用 debug 日志确认（实测）：

ts=...Z level=debug msg="Loading configuration from file: /opt/sqlpage/conf/sqlpage.toml" target=sqlpage::app_config

1.2 环境变量规则

所有配置参数都可以用环境变量设置：变量名为参数名的大写形式，可选加 SQLPAGE_ 前缀。例如 listen_on 对应 LISTEN_ON 或 SQLPAGE_LISTEN_ON；SQLPAGE_CONFIGURATION_DIRECTORY 是唯一能设置配置目录本身的方式。工作目录或其父目录若存在 .env 文件，SQLPage 会自动加载（实测 debug 日志："No .env file found, using only environment variables and configuration files"）。

注意：configuration_directory 不能在配置文件里设置（否则鸡生蛋问题），只能通过环境变量或命令行参数。另外，同一参数尽量只在一处设置——命令行参数的覆盖行为有明确日志佐证（实测 debug 日志："Setting web root to value from the command line: /opt/sqlpage/www"），环境变量覆盖配置文件也实测成立（LISTEN_ON=127.0.0.1:9090 覆盖 toml 中的 listen_on，见命令运维篇）。

二、核心参数与默认值

以下为 v0.47.0 生产常用参数（完整清单见官方 configuration.md，查询日期 2026-10-28）：

三、生产样例与逐项生效验证

3.1 生产样例 sqlpage.toml

# /opt/sqlpage/conf/sqlpage.toml —— SQLPage 主配置（v0.47.0）
listen_on = "0.0.0.0:8080"          # 监听地址与端口（默认 0.0.0.0:8080）
web_root = "/opt/sqlpage/www"       # .sql 页面根目录（默认当前工作目录）
database_url = "sqlite:////opt/sqlpage/data/app.db?mode=rwc"  # 内置 SQLite，mode=rwc 自动建库
environment = "production"          # production：隐藏错误详情并缓存 sql 文件
compress_responses = true           # 对支持的客户端启用 gzip 压缩
max_uploaded_file_size = 10485760   # 表单/上传大小上限 10 MiB（默认 5 MiB）
content_security_policy = "script-src 'self' 'nonce-{NONCE}'"  # CSP，{NONCE} 每请求随机

写入后重启并确认启动横幅：

systemctl daemon-reload && systemctl restart sqlpage && sleep 2
journalctl -u sqlpage --since "-15s" --no-pager -o cat | grep "started successfully"

实测输出：

ts=2026-10-28T01:55:32.164Z level=info msg=" ✨ SQLPage v0.47.0 started successfully! ✨  View your website at: 🔗 http://localhost:8080 (also accessible from other devices using your IP address)  Create your pages with SQL files in: 💻 /opt/sqlpage/www  Happy coding! 🚀" target=sqlpage::webserver::http

3.2 database_url：库文件位置

安装篇的默认行为会把库建在 /opt/sqlpage/sqlpage/sqlpage.db；显式配置 database_url 后：

ls -la /opt/sqlpage/data/

实测输出：

-rw-r--r-- 1 sqlpage sqlpage 0 Oct 28 01:55 app.db

mode=rwc 表示不存在则创建（read-write-create）。SQLite 连接串是四段斜杠（sqlite:////绝对路径）。注意：切换 database_url 只是指向新库，旧库数据不会自动迁移——实测切换后首页的演示表在新库重新 CREATE TABLE IF NOT EXISTS 建出，旧库 sqlpage.db 仍在原地留作迁移源。

3.3 environment：报错信息从暴露到隐藏

用一页故意写错的 SQL 做对照（引用不存在的表）：

-- /opt/sqlpage/www/error-demo.sql
SELECT * FROM no_such_table;

**development（默认）**下访问的实测回显（HTTP 200，详情完整暴露）：

In "error-demo.sql": The following error occurred while executing an SQL statement:
error returned from database: (code: 1) no such table: no_such_table
error-demo.sql: line 2

页面甚至附提示："You can hide error messages like this one from your users by setting the 'environment' configuration option to 'production'."

production 下重启后再访问：状态码变为 HTTP 500，正文只剩通用提示 "An error occurred / We are sorry, but an error occurred while generating this page."——表名、语句、行号全部消失。生产环境必须显式设置 environment = "production"。

顺带一个实测发现：SQLite 中 SELECT 1/0 并不报错（返回 NULL），想造一个真错误得用不存在的表/函数。

3.4 compress_responses：gzip 压缩

curl -s -o /dev/null -D - -H "Accept-Encoding: gzip" http://127.0.0.1:8080/ | grep -iE "content-encoding|vary|HTTP"
curl -s -o /dev/null -D - http://127.0.0.1:8080/ | grep -iE "content-encoding|HTTP"

实测输出（开压缩 / 不带 Accept-Encoding 的对照）：

HTTP/1.1 200 OK
content-encoding: gzip
vary: accept-encoding
---
HTTP/1.1 200 OK

官方文档同时提醒：压缩会增加 CPU 开销，流式渲染的长页面会因缓冲而略延迟出首帧，按需开启。

3.5 content_security_policy：nonce 占位符注入

curl -s -o /dev/null -D - http://127.0.0.1:8080/ | grep -i "content-security"

实测输出：

content-security-policy: script-src 'self' 'nonce-1929757301760367755'

配置串里的 'nonce-{NONCE}' 被替换为每请求一次的随机 nonce。若引入需要 eval 的第三方脚本导致 CSP 报错，可临时将该参数置空串禁用 CSP（官方文档明示的排障手段），但不应长期关闭。

3.6 site_prefix：子路径部署

在 toml 追加 site_prefix = "/sqlpage/" 并重启：

curl -s -o /dev/null -w "GET /          -> HTTP %{http_code}\n" http://127.0.0.1:8080/
curl -s -o /dev/null -w "GET /sqlpage/  -> HTTP %{http_code}\n" http://127.0.0.1:8080/sqlpage/
curl -s http://127.0.0.1:8080/sqlpage/ | grep -c "由 SQL 驱动的第一个页面"

实测输出：

GET /          -> HTTP 308
GET /sqlpage/  -> HTTP 200
1

根路径 308 重定向到前缀路径，/sqlpage/ 正常渲染 index.sql 的内容。这与 Nginx 反代把 SQLPage 挂在域名子路径（如 https://example.com/sqlpage/）配合使用。验证后从 toml 移除该行，重启恢复（实测 GET / 回到 200）。

3.7 max_uploaded_file_size：上传上限

该项难以在不构造表单的场景直接观测，行为依据官方文档：超过上限的表单提交/文件上传将被拒绝（默认 5 MiB，本例调至 10 MiB = 10485760 字节）。此参数与邮件附件上限 max_email_attachment_size（默认 10 MiB）相互独立（来源：官方 configuration.md，2026-10-28；标注为"命令+预期结果"，未做上传实测）。

四、数据库连接与连接管理

4.1 连接串写法

database_url 一个参数囊括引擎、地址、库名与附加参数（来源：官方 configuration.md 的 Database connection strings，2026-10-28）：

sqlite://sqlpage.db?mode=rwc                      # SQLite（相对配置目录）
postgres://my_user:p%40ss@localhost:5432/my_database?sslmode=verify-ca&sslrootcert=/etc/sqlpage/ca.pem
mysql://user:pass@localhost:3306/mydb?collation=utf8mb4_unicode_ci
mssql://user:pass@host:1433/db
DSN=MyDatabase                                    # ODBC（unixODBC 管理器已内置于二进制）

要点：口令等特殊字符需百分号编码（@ → %40）；PostgreSQL 支持 sslmode（disable/allow/verify-ca/verify-full）与客户端证书；database_password 参数可在连接串之外单独传口令，便于把连接串入库配置管理。

4.2 连接初始化与清理脚本

配置目录下的两个可选文件在连接生命周期执行：on_connect.sql（每个新连接建立时，如 PostgreSQL SET TIME ZONE 'UTC'; SET search_path = my_schema;、SQLite ATTACH DATABASE ... AS aux;）；on_reset.sql（请求结束归还连接前，如 ROLLBACK; 或 PostgreSQL DISCARD ALL;），用于避免上一请求的临时表/未提交事务污染下一请求（来源：官方 configuration.md 的 Connection management 一节）。

4.3 迁移机制

配置目录 migrations/ 下的 <时间戳>_<名称>.sql 在服务启动时自动按序执行一次，记录写入库表 _sqlx_migrations（实测：创建 20261028015639_init_demo_schema.sql 后重启，日志出现 "Found 1 migrations: [20261028015639] init demo schema"，sqlite3 .tables 可见脚本中的 app_log 表已建出）。迁移文件的生成命令 create-migration 见命令运维篇。

五、自定义组件与目录安全

5.1 自定义组件

在配置目录 templates/ 下放 Handlebars 模板即可新增组件，例如 templates/my_component.handlebars：

<ul>
    {{#each_row}}
        <li>Value of my column: {{my_column}}</li>
    {{/each_row}}
</ul>

页面里 SELECT 'my_component' AS component, ... AS my_column; 即可调用（来源：官方 configuration.md 的 Custom components 一节）。

5.2 目录安全注意

官方 configuration.md 明确两条红线：静态文件服务跟随符号链接，不要在 web_root 下放置指向私有路径（如 sqlpage/ 配置目录）或站点外文件的符号链接；配置目录里可能含数据库口令相关配置，不要落在 web_root 公开路径之下（来源：官方文档及 SECURITY.md 引用，2026-10-28）。本系列的 /opt/sqlpage/www（公开）与 /opt/sqlpage/conf、/opt/sqlpage/data（私有）分离布局即基于此。

六、配置排障实录

1. "配置文件好像没生效"：现象是改了 toml、重启后行为变了，但 info 日志仍显示 Configuration loaded from /opt/sqlpage/sqlpage。结论：info 日志显示的是配置目录，不是文件；LOG_LEVEL=sqlpage=debug 重启即可看到 Loading configuration from file: /opt/sqlpage/conf/sqlpage.toml 与完整的 Loaded configuration: AppConfig {...} 转储（实测 16 条 debug 日志），可逐字段核对生效值。
2. 换了 database_url，数据"没了"：实测把库从默认 /opt/sqlpage/sqlpage/sqlpage.db 切到 /opt/sqlpage/data/app.db 后，旧表数据不会跟过来——新库从零建表。要么把旧库文件改名/拷贝到新路径，要么用 sqlite3 旧库 ".backup 新库" 先迁移再切换。
3. CSP 报错导致页面脚本不执行：浏览器控制台出现 CSP violation 时，先检查是否引入了默认 CSP 未放行的脚本域；排障期可将 content_security_policy 置空串快速定位（官方明示），修复后务必恢复。
4. 生产环境忘记设置 environment：SQL 报错页把表名、SQL、行号全部返回给访问者（HTTP 200），信息泄露风险高。对照实测见 3.3 节，务必在生产 toml 中显式 environment = "production"。

下一篇进入命令行与日常运维：《SQLPage 0.47.0 常用 CLI 命令与运维实战》。