Ubuntu 22.04 安装 Datasette 0.65.5 指南

在 Ubuntu 22.04 上从零安装 Datasette 0.65.5：pipx 与 venv+pip 两种形态实测、systemd 托管、nginx 反向代理与端到端验证，含 tzdata 交互卡住等排障实录与卸载清理步骤。

DatasetteDatasetteSQLitePython2026/10/25

Ubuntu 22.04 安装 Datasette 0.65.5 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Datasette 0.65.5，覆盖 pipx 与 venv+pip 两种官方安装形态，并用 systemd 托管、nginx 反向代理对外发布，最后用一个自建 SQLite 库做端到端验证。全部命令与回显已在 Ubuntu 22.04.5 LTS（Python 3.10.12）实测通过。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Python：3.10.12（系统自带，python3 --version 实测）
  • pipx：1.0.0（Ubuntu 官方仓库）
  • Datasette：0.65.5（PyPI 当前最新稳定版，2026-09-17 发布）
  • 内嵌 ASGI 服务器：uvicorn 0.54.0（随 datasette 自动安装）
  • SQLite：3.37.2（随 Python 3.10 标准库）
  • nginx：1.18.0（Ubuntu 官方仓库，用于反向代理）
  • 服务形态：datasette 专用用户运行，监听 127.0.0.1:8001，nginx 监听 80 反代
  • 数据与配置目录：/srv/datasette/app；程序虚拟环境：/opt/datasette/venv

二、前置条件

开始安装前确认以下条件全部满足，避免中途返工：

  1. 一台可联网的 Ubuntu 22.04 机器，有 sudo 权限。
  2. Python 版本 ≥ 3.10（Datasette 0.65.5 的硬性要求，PyPI requires_python 字段）。实测本机：
python3 --version

Python 3.10.12
  1. 安装 venv 与 sqlite3 命令行（演示建库用）：
sudo apt-get update
sudo apt-get install -y python3-venv sqlite3

⚠️ 注意：以下所有涉及对外服务的步骤默认你把 Datasette 绑定在 127.0.0.1，由 nginx 统一对外；不要一开始就把 --host 0.0.0.0 暴露到公网，见「十、常见问题」Q4。

三、版本选型说明

PyPI 上当前同时存在两条线（查询日期 2026-10-25）：

版本线最新版发布日期性质建议
0.65.x0.65.52026-09-17稳定版生产与学习首选，本文实测对象
1.0 alpha1.0a412026-09-24预发布版仅体验新特性，勿上生产

可用 pip index versions datasette 或查看 PyPI 页面复核最新版本号。本文两条安装路线均安装 0.65.5。

四、方案 A：pipx 在线安装（官方推荐的命令行形态）

4.1 方案说明

pipx 会为每个 Python 命令行工具创建独立虚拟环境，并把可执行文件链接到 ~/.local/bin，既隔离依赖又不污染系统 Python。官方文档把 pipx 列为推荐的本地安装方式，适合在个人服务器上以 CLI 方式使用 Datasette。

4.2 安装 pipx

sudo DEBIAN_FRONTEND=noninteractive apt-get install -y pipx

⚠️ 排障实录：直接 sudo apt-get install -y pipx 时，依赖包 tzdata 会弹出交互式时区选择界面并停住：

  2. America     5. Arctic     8. Europe    11. US
  3. Antarctica  6. Asia       9. Indian    12. Etc
Geographic area:

脚本化安装时会一直卡在这里。加 DEBIAN_FRONTEND=noninteractive 前缀即可跳过交互，实测安装后时区保持 Etc/UTC，需要调整可再跑 dpkg-reconfigure tzdata。

验证：

pipx --version

1.0.0

4.3 用 pipx 安装 Datasette

pipx install datasette

实测回显（节选）：

  installed package datasette 0.65.5, installed using Python 3.10.12
  These apps are now globally available
    - datasette
done! ✨ 🌟 ✨

4.4 验证安装

datasette --version
which datasette
pipx list --short

实测回显：

datasette, version 0.65.5

/root/.local/bin/datasette

datasette 0.65.5

💡 说明：pipx 把可执行文件链接到当前用户的 ~/.local/bin/（root 用户即 /root/.local/bin/），虚拟环境本体在 ~/.local/pipx/venvs/datasette/。如果换用户登录发现找不到命令，确认该用户的 PATH 是否包含 ~/.local/bin。

五、方案 B：python3-venv + pip 安装（生产服务形态）

5.1 方案说明

要用 systemd 托管、以专用低权限用户长期运行 Datasette，更合适的形态是：建一个专用用户、一个固定位置的 venv、一份固定的数据目录，再由 systemd 拉起进程。本节完整走一遍这个流程。

5.2 创建专用用户与目录

sudo useradd --system --shell /usr/sbin/nologin datasette
sudo mkdir -p /opt/datasette /srv/datasette/app
sudo chown -R datasette:datasette /srv/datasette

验证用户已建好：

id datasette

实测回显：

uid=999(datasette) gid=999(datasette) groups=999(datasette)

5.3 创建 venv 并安装 Datasette

sudo python3 -m venv /opt/datasette/venv
sudo /opt/datasette/venv/bin/pip install --upgrade pip
sudo /opt/datasette/venv/bin/pip install datasette

pip install datasette 实测回显（节选，共 26 个依赖包）：

Installing collected packages: typing_extensions, PyYAML, python-multipart, pluggy, platformdirs, mergedeep, MarkupSafe, janus, itsdangerous, idna, hupper, h11, click, certifi, aiofiles, uvicorn, Jinja2, httpcore, flexparser, flexcache, exceptiongroup, click-default-group, asgiref, asgi-csrf, anyio, httpx, datasette

Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 PyYAML-6.0.3 aiofiles-25.1.0 anyio-4.15.1 asgi-csrf-0.11 asgiref-3.12.1 certifi-2026.10.23 click-8.5.0 click-default-group-1.2.4 datasette-0.65.5 exceptiongroup-1.3.1 flexcache-0.3 flexparser-0.4 h11-0.16.0 httpcore-1.0.9 httpx-0.28.1 hupper-1.12.1 idna-3.20 itsdangerous-2.2.0 janus-2.0.0 mergedeep-1.3.4 platformdirs-4.12.4 pluggy-1.7.0 python-multipart-0.0.32 typing_extensions-4.16.0 uvicorn-0.54.0

验证 venv 内版本：

/opt/datasette/venv/bin/datasette --version

datasette, version 0.65.5

💡 说明：从回显可见 Datasette 的依赖很轻——核心是 uvicorn（ASGI 服务器）、Jinja2（模板）、click（CLI）、httpx（内部请求）、asgi-csrf 与 itsdangerous（安全签名）。没有重型科学计算依赖，安装体积很小。

5.4 systemd 托管

先为签名 cookie 生成一个随机密钥（用于 --root 登录链接、签名 cookie 等场景）：

openssl rand -hex 32

实测输出（每次生成不同，此处为本机实测值）：

a446cd535ccd575d8260b14e2a2dfd90b1b148d4306e0e793e393bd5b5d131cf

创建单元文件 /etc/systemd/system/datasette.service：

[Unit]
Description=Datasette data exploration service
Documentation=https://docs.datasette.io/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=datasette
Group=datasette
WorkingDirectory=/srv/datasette/app
Environment="DATASETTE_SECRET=a446cd535ccd575d8260b14e2a2dfd90b1b148d4306e0e793e393bd5b5d131cf"
ExecStart=/opt/datasette/venv/bin/datasette /srv/datasette/app --host 127.0.0.1 --port 8001
Restart=on-failure
RestartSec=3
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

逐项说明：

  • User/Group=datasette：以低权限专用用户运行，配合 NoNewPrivileges、PrivateTmp 收敛权限；
  • WorkingDirectory=/srv/datasette/app 且 ExecStart 的第一个参数也是该目录：这是 Datasette 的「配置目录」模式——目录内的 .db 文件、metadata.json、settings.json、插件目录都会被自动识别（详见《Datasette 0.65.5 配置参数详解》）；
  • Environment="DATASETTE_SECRET=..."：上一步生成的随机密钥，换成你自己的值；
  • --host 127.0.0.1 --port 8001：只绑回环地址，对外流量由第七节 nginx 反代进来；
  • Restart=on-failure + RestartSec=3：进程异常退出 3 秒后自动拉起。

启用并启动服务：

sudo systemctl daemon-reload
sudo systemctl enable datasette
sudo systemctl start datasette

验证运行状态：

sudo systemctl status datasette --no-pager

实测回显（节选）：

● datasette.service - Datasette data exploration service
     Loaded: loaded (/etc/systemd/system/datasette.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 10:07:58 UTC; 26min ago
       Docs: https://docs.datasette.io/
   Main PID: 5295 (datasette)
      Tasks: 4 (limit: 3852)
     Memory: 31.3M
             └─5295 /opt/datasette/venv/bin/python3 /opt/datasette/venv/bin/datasette /srv/datasette/app --host 127.0.0.1 --port 8001

systemctl is-enabled datasette
systemctl is-active datasette

enabled
active

六、nginx 反向代理（对外发布）

Datasette 自身监听 127.0.0.1:8001，不直接对公网开放；用 nginx 在 80 端口反代，统一承接域名、TLS 与访问控制。

安装 nginx：

sudo apt-get install -y nginx

实测版本：

nginx -v

nginx version: nginx/1.18.0 (Ubuntu)

新建站点配置 /etc/nginx/conf.d/datasette.conf：

server {
    listen 80;
    server_name _;

    access_log /var/log/nginx/datasette.access.log;
    error_log  /var/log/nginx/datasette.error.log;

    location / {
        proxy_pass http://127.0.0.1:8001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 60s;
    }
}

关键项说明：proxy_set_header Host $host 保证 Datasette 生成的绝对链接与 .json 端点里的 URL 主机名正确；X-Forwarded-Proto 为后续上 HTTPS 预留；proxy_read_timeout 60s 覆盖慢查询场景（Datasette 默认 SQL 超时 1000ms，正常查询远快于此）。

校验配置并 reload：

sudo nginx -t
sudo systemctl reload nginx

实测回显：

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

端到端验证（经 nginx 访问首页）：

curl -s -o /dev/null -w "homepage http_code=%{http_code}\n" http://127.0.0.1/

homepage http_code=200

确认监听分布符合预期（80 对全网、8001 仅回环）：

ss -ltn | grep -E ':80 |:8001 '

LISTEN 0      2048       127.0.0.1:8001       0.0.0.0:*
LISTEN 0      511          0.0.0.0:80         0.0.0.0:*

七、最小数据演示与端到端验证

服务搭好后，用一个小库验证「建库 → 挂载 → 查询」全链路。新建演示目录并建库：

sudo mkdir -p /srv/datasette/demo && cd /srv/datasette/demo
sqlite3 demo.db "CREATE TABLE notes (id INTEGER PRIMARY KEY, title TEXT, created TEXT);"
sqlite3 demo.db "INSERT INTO notes (title, created) VALUES ('第一条笔记', datetime('now')), ('第二条笔记', datetime('now'));"
sqlite3 demo.db "select * from notes;"

实测回显：

1|第一条笔记|2026-10-25 10:35:24
2|第二条笔记|2026-10-25 10:35:24

用 --get 直接发一次 HTTP 请求验证渲染结果（该方式启动、请求、打印、退出一条龙，适合验证）：

/opt/datasette/venv/bin/datasette serve demo.db --port 8006 --get /demo/notes.json

实测回显（节选）：

{"database": "demo", "table": "notes", "is_view": false, "human_description_en": "", "rows": [[1, "第一条笔记", "2026-10-25 10:35:24"], [2, "第二条笔记", "2026-10-25 10:35:24"]], "truncated": false, "filtered_table_rows_count": 2, ... "columns": ["id", "title", "created"], "primary_keys": ["id"], ...}

返回 JSON 包含两行笔记与列定义，说明从进程启动到 SQL 执行再到 JSON 序列化的链路完全正常。日常使用时去掉 --get，直接 datasette serve demo.db 即可在浏览器访问 http://127.0.0.1:8001/。

💡 说明：把 demo.db 放进 /srv/datasette/app/ 即可被第五节 systemd 托管的实例自动挂载（配置目录模式），无需改启动命令；放完后 sudo systemctl restart datasette 生效。

八、方案对比与选择建议

维度方案 A：pipx方案 B：venv + pip + systemd
适用场景个人 CLI 使用、临时起服务看数据生产常驻服务、多实例、反向代理
安装位置~/.local/pipx/venvs/datasette//opt/datasette/venv/（固定路径）
进程托管无（前台或自己配）systemd，开机自启 + 失败重启
运行身份当前用户专用低权限用户 datasette
插件管理datasette install <插件>venv/bin/pip install <插件> 或 datasette install
升级方式pipx upgrade datasettevenv/bin/pip install -U datasette

选择建议：先在本机用方案 A 体验和验证数据文件；确认要长期对外服务时，按方案 B 部署并用 nginx 反代。两者可以共存，互不干扰。

九、基础配置说明

本节只给「装上就能用」的最小配置，完整参数逐项实测见《Datasette 0.65.5 配置参数详解》。

  • 元数据 metadata.json：放在 /srv/datasette/app/ 下自动加载，可为实例/库/表挂标题、来源、许可证、默认排序与预定义查询；
  • 运行参数 settings.json：同目录自动加载，控制 default_page_size、max_returned_rows、sql_time_limit_ms、allow_download 等运行时护栏；
  • 命令行覆盖：任何 setting 都可用 --setting 名称 值 临时覆盖，如 datasette serve app --setting default_page_size 20；
  • 查看全部可配项：datasette --help-settings 列出 19 项运行时参数及默认值（实测输出见《Datasette 0.65.5 配置参数详解》）。

十、常见问题（FAQ）

Q1：apt-get install pipx 卡在时区选择界面？ tzdata 包的交互式提示所致。用 sudo DEBIAN_FRONTEND=noninteractive apt-get install -y pipx 跳过（见 4.2 排障实录）；已卡住的终端输入对应数字回车即可继续。

Q2：datasette: command not found？ pipx 形态下确认 ~/.local/bin 在 PATH 中（pipx ensurepath 可自动修复）；venv 形态下使用绝对路径 /opt/datasette/venv/bin/datasette。

Q3：启动报错 Address already in use？ 8001 被占用。用 ss -ltnp | grep 8001 找到占用进程，或换端口 --port 8002。

Q4：可以直接 --host 0.0.0.0 对外吗？ 可以但需先想清楚权限：Datasette 默认允许任何访问者执行只读 SQL 并下载整个库文件。对外发布前建议用元数据 allow 块收紧权限，或保持 127.0.0.1 由 nginx 反代并在 nginx 层加认证/限流，权限配置实测见《Datasette 0.65.5 配置参数详解》第七节。

Q5：服务启动了但首页看不到我的库？ 配置目录模式下只有启动目录内的 .db 会被挂载；确认库文件路径与 WorkingDirectory 一致，且 datasette 用户对该文件有读权限（sudo -u datasette ls -l /srv/datasette/app/）。

十一、卸载与清理

pipx 形态：

pipx uninstall datasette

实测回显：

uninstalled datasette! ✨ 🌟 ✨

venv + systemd 形态（按顺序逐条执行）：

sudo systemctl stop datasette
sudo systemctl disable datasette
sudo rm /etc/systemd/system/datasette.service
sudo systemctl daemon-reload
sudo rm -rf /opt/datasette/venv
sudo rm -rf /srv/datasette          # 含数据与配置，确认备份后再删
sudo userdel datasette

nginx 反代配置按需保留或删除 /etc/nginx/conf.d/datasette.conf 后 sudo systemctl reload nginx。

十二、参考链接