Ubuntu 22.04 安装 SQLPage 0.47.0 指南

Ubuntu 22.04.5 LTS 安装 SQLPage v0.47.0 实测：官方二进制下载与 SHA-256 校验、/opt/sqlpage 目录布局与专用账号、text/list/table 三组件首页、systemd 托管开机自启与 HTTP 验收。

SQLPageSQLPageUbuntu 22.04SQLRust建站2026/10/28

Ubuntu 22.04 安装 SQLPage 0.47.0 指南

目标：在一台 Ubuntu 22.04.5 LTS 服务器上完成 SQLPage v0.47.0 的生产化安装——下载官方预编译二进制并做 SHA-256 完整性校验、规划 /opt/sqlpage 目录布局、创建专用系统账号、编写第一个由 text/list/table 三个组件渲染的 SQL 页面，最后交给 systemd 托管并验证开机自启。全部命令与输出均为实测回显；选型背景见《SQLPage 0.47.0 介绍与选型指南》（https://www.quzuo.net/document/qeGaJyffJQTk）。

一、安装方式与环境准备

1.1 安装方式选择

SQLPage 官方的分发形态是 GitHub Releases 上的预编译二进制压缩包，按平台提供 sqlpage-linux.tgz、sqlpage-macos.tgz、sqlpage-windows.zip 与 AWS Lambda 部署包四种产物（来源：GitHub Releases v0.47.0 资产清单，查询日期 2026-10-28）。Ubuntu 服务器上的生产安装路径就是：下载 linux 版压缩包 → 校验 → 布置目录 → systemd 托管。整个过程不需要任何语言运行时，也不需要编译工具链。

本篇实测环境：

项目值
操作系统Ubuntu 22.04.5 LTS（x86_64）
目标版本SQLPage v0.47.0（2026-10-16 发布的最新稳定版）
安装目录/opt/sqlpage
监听端口8080（默认）
执行账号sqlpage（系统账号，无可登录 shell）

1.2 环境准备

确认基础工具与外网连通性（下载走 GitHub Releases）：

uname -m            # 确认架构，x86_64 下载 sqlpage-linux.tgz
which curl sha256sum useradd
curl -sI --max-time 10 https://github.com | head -1

实测输出：

x86_64
/usr/bin/curl
/usr/bin/sha256sum
/usr/sbin/useradd
HTTP/2 200

如果服务器计划对外开放，记得放行端口（默认监听 8080）：

ufw allow 8080/tcp    # 使用 ufw 的场景；云服务器还需在安全组放行

二、下载与校验官方二进制

2.1 下载压缩包

mkdir -p /tmp/sqlpage-dl && cd /tmp/sqlpage-dl
curl -sL -o sqlpage-linux.tgz \
  https://github.com/sqlpage/SQLPage/releases/download/v0.47.0/sqlpage-linux.tgz
ls -la sqlpage-linux.tgz

实测输出：

-rw-r--r-- 1 root root 12970149 Oct 28 01:49 sqlpage-linux.tgz

2.2 SHA-256 完整性校验

GitHub Releases API 会公布每个资产的 digest 字段（sha256）。v0.47.0 的 sqlpage-linux.tgz 官方摘要为 b566a5d609e2894cf7658c5a421828de3a3b0bc993f405713ee2d2513d27ae5c（来源：GitHub API releases/latest 的 assets[].digest，查询日期 2026-10-28）。下载后本地计算比对：

sha256sum sqlpage-linux.tgz

实测输出：

b566a5d609e2894cf7658c5a421828de3a3b0bc993f405713ee2d2513d27ae5c  sqlpage-linux.tgz

与官方摘要一致，校验通过。升级到新版本时必须重复这一步，摘要值随版本变化。

2.3 解压与包内容

tar tzf sqlpage-linux.tgz

实测输出（包内容清单）：

sqlpage.bin
sqlpage/migrations/
sqlpage/migrations/README.md
sqlpage/templates/
sqlpage/templates/README.md
sqlpage/sqlpage.json

包里只有两样东西：主程序 sqlpage.bin（解压后 34 114 328 字节）和一个 sqlpage/ 资源目录（官方资源配置样例、空的模板与迁移目录）。

三、安装布局与专用账号

3.1 目录布局

生产环境建议固定如下布局（职责分离，后续配置与运维都基于它）：

/opt/sqlpage/
├── bin/sqlpage          # 主程序（sqlpage.bin 改名，便于调用）
├── conf/                # sqlpage.toml 配置文件（见配置篇）
├── data/                # SQLite 数据库文件
├── www/                 # web root：.sql 页面与静态资源
└── resources/           # 发布包自带的 sqlpage/ 资源目录

执行安装：

cd /tmp/sqlpage-dl
tar xzf sqlpage-linux.tgz
useradd -r -s /usr/sbin/nologin -d /opt/sqlpage sqlpage
mkdir -p /opt/sqlpage/{bin,conf,data,www}
cp sqlpage.bin /opt/sqlpage/bin/sqlpage
cp -r sqlpage /opt/sqlpage/resources
chown -R sqlpage:sqlpage /opt/sqlpage
ls -la /opt/sqlpage

实测输出：

/opt/sqlpage:
total 24
drwxr-xr-x 6 sqlpage sqlpage 4096 Oct 28 01:50 .
drwxr-xr-x 1 root    root    4096 Oct 28 01:50 ..
drwxr-xr-x 2 sqlpage sqlpage 4096 Oct 28 01:50 bin
drwxr-xr-x 2 sqlpage sqlpage 4096 Oct 28 01:50 conf
drwxr-xr-x 4 sqlpage sqlpage 4096 Oct 28 01:50 resources
drwxr-xr-x 2 sqlpage sqlpage 4096 Oct 28 01:50 www

确认版本：

/opt/sqlpage/bin/sqlpage --version

实测输出：

sqlpage 0.47.0

四、第一个 SQL 页面

4.1 index.sql：text + list + table 三组件

在 web root 写入 index.sql。文件里每条 SELECT 的第一列 component 指定渲染组件，其余列是组件参数：

-- /opt/sqlpage/www/index.sql
SELECT 'text' AS component,
       '由 SQL 驱动的第一个页面' AS title,
       '本页面没有任何传统后端代码，仅由一条 SELECT 语句渲染。' AS contents_md;

SELECT 'list' AS component,
       '页面用到的组件' AS title;
SELECT 'text' AS title, '输出一段富文本' AS description
UNION ALL
SELECT 'list' AS title, '渲染无序列表' AS description
UNION ALL
SELECT 'table' AS title, '渲染查询结果表格' AS description;

-- 内置 SQLite 演示表
CREATE TABLE IF NOT EXISTS demo_product (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    price REAL NOT NULL
);
INSERT OR IGNORE INTO demo_product (id, name, price) VALUES
    (1, 'SQLite', 0.0),
    (2, 'PostgreSQL', 0.0),
    (3, 'MySQL', 0.0);

SELECT 'table' AS component,
       '内置 SQLite 演示表' AS title;
SELECT id, name, price FROM demo_product ORDER BY id;

三个组件各司其职：text 输出标题与 Markdown 富文本；list 把查询结果逐行渲染成列表；table 把查询结果渲染成可排序的表格。注意 CREATE TABLE IF NOT EXISTS 与 INSERT OR IGNORE 保证了页面可重复刷新——每次请求都会执行整个文件。

五、systemd 托管与开机自启

5.1 编写 unit 文件

# /etc/systemd/system/sqlpage.service
[Unit]
Description=SQLPage web server
After=network.target

[Service]
User=sqlpage
Group=sqlpage
WorkingDirectory=/opt/sqlpage
ExecStart=/opt/sqlpage/bin/sqlpage --web-root /opt/sqlpage/www
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

--web-root 显式指向页面目录；WorkingDirectory 决定了相对路径（自动创建的配置目录 ./sqlpage）的落点。启动并设置自启：

systemctl daemon-reload
systemctl enable --now sqlpage

实测输出：

Created symlink /etc/systemd/system/multi-user.target.wants/sqlpage.service → /etc/systemd/system/sqlpage.service.

5.2 状态确认

systemctl status sqlpage --no-pager -l | head -15

实测输出：

● sqlpage.service - SQLPage web server
     Loaded: loaded (/etc/systemd/system/sqlpage.service; enabled; vendor preset: enabled)
     Active: active (running) since Wed 2026-10-28 01:51:08 UTC; 3s ago
   Main PID: 165 (sqlpage)
      Tasks: 9 (limit: 2932)
     Memory: 3.6M
        CPU: 21ms
     CGroup: /system.slice/sqlpage.service
             └─165 /opt/sqlpage/bin/sqlpage --web-root /opt/sqlpage/www

Oct 28 01:51:08 sqlpage systemd[1]: Started SQLPage web server.

注意 Memory: 3.6M——空闲常驻内存仅 3.6 MB，这是选型篇里资源对比的实测依据。

5.3 启动日志解读

journalctl -u sqlpage --no-pager -o cat | head -5

实测输出：

ts=2026-10-28T01:51:08.657Z level=info msg="Configuration directory does not exist, creating it: ./sqlpage" target=sqlpage::app_config
ts=2026-10-28T01:51:08.657Z level=info msg="No DATABASE_URL provided, /opt/sqlpage/sqlpage/sqlpage.db is writable, creating a new database file." target=sqlpage::app_config
ts=2026-10-28T01:51:08.657Z level=info msg="Configuration loaded from ./sqlpage" target=sqlpage::app_config
ts=2026-10-28T01:51:08.657Z level=info msg="Not applying database migrations because './sqlpage/migrations' does not exist" target=sqlpage::webserver::database::migrations

四行日志各有信息量：

  1. SQLPage 自动创建了配置目录 /opt/sqlpage/sqlpage/（配置目录默认是工作目录下的 ./sqlpage）；
  2. 未配置 database_url 时自动在配置目录创建 SQLite 文件库——零配置即可跑；
  3. 迁移目录不存在则跳过迁移。

这套"自动配置目录 + 自动建库"是默认行为的起点，配置篇会把它规范化为显式配置文件与独立数据目录。

六、页面验收与常见安装问题

6.1 HTTP 验收

curl -s -o /dev/null -w "index:   HTTP %{http_code}\n" http://127.0.0.1:8080/
curl -s http://127.0.0.1:8080/ | grep -oE "(由 SQL 驱动的第一个页面|页面用到的组件|<table)" | sort -u
curl -s -o /dev/null -w "missing: HTTP %{http_code}\n" http://127.0.0.1:8080/missing.sql

实测输出：

index:   HTTP 200
<table
由 SQL 驱动的第一个页面
页面用到的组件
missing: HTTP 404

三个断言全部通过：首页 200、text/list/table 组件内容出现在 HTML 中、不存在的路径正确返回 404。外部机器访问 http://<服务器IP>:8080/ 应得到同样结果（不通则检查防火墙/安全组与 listen_on 配置）。

6.2 常见安装问题实录

  1. 架构下错包：ARM 服务器下载了 x86_64 包，运行时报"cannot execute binary file"。先 uname -m 再选包，aarch64 同样使用 sqlpage-linux.tgz（包内含通用 Linux 构建）。
  2. 8080 被占用：启动失败且日志出现地址绑定错误。ss -ltnp | grep 8080 找到占用进程，或改用配置项 listen_on/环境变量 LISTEN_ON 换端口（见配置篇与命令运维篇）。
  3. 权限不足导致库文件建不出来：若把 WorkingDirectory 指到 sqlpage 用户不可写目录，自动建库会失败。要么按本篇布局 chown -R sqlpage:sqlpage /opt/sqlpage，要么显式配置 database_url 到可写路径。
  4. 下载校验失败：sha256 与官方不一致通常是下载不完整或被代理篡改，重新下载；生产环境建议把摘要比对写进发布脚本。

安装到此完成。下一步把默认行为规范化为显式配置文件，请继续阅读《SQLPage 0.47.0 配置详解与参数生效验证》；日常升级、日志与备份操作见《SQLPage 0.47.0 常用 CLI 命令与运维实战》。