Ubuntu 22.04 安装 Liwan 1.8 指南

Liwan 是一个用 Rust 编写的自托管隐私优先 Web 分析服务，最大特点是「单二进制、内嵌数据库、零外部依赖」：一个 49 MB 左右的静态链接可执行文件就是全部，事件数据落在内嵌的 DuckDB 文件里，账号与项目配置落在 SQLite 文件里，不需要安装 PostgreSQL、MySQL、Redis 中的任何一个。本文以一台 Ubuntu 22.04 LTS x86_64 服务器为例，从零完成：下载官方预编译二进制 → 安装到本地 bin 目录 → 首次启动并创建管理员 → 创建站点实体 → 嵌入追踪脚本 → 发送测试流量并在看板看到数据 → 配置 systemd 开机自启。文中所有命令与输出均来自在 Ubuntu 22.04.5 LTS（x86_64）上的实际安装过程，Liwan 版本为 v1.8.2。

关于 Liwan 的定位、隐私模型与同类产品对比，请先阅读《Liwan 1.8 介绍与选型指南》；启动后的参数调优见《Liwan 1.8 配置参数详解》；日常维护、备份升级见《Liwan 1.8 运维实操指南》。

💡 技术拓展：为什么 Liwan 不用装数据库。Liwan 的报表查询跑在内嵌的 DuckDB 列式引擎上，事件追加写入 DuckDB 文件，账号/项目等小体量元数据用 SQLite 保存。两者都以「库文件」而非「数据库服务」的形式存在，进程启动即打开、关闭即释放，这正是单二进制方案能把运维面压到极致的原因。代价是单机天花板：没有主从、没有分片，亿级事件量需要另选 ClickHouse 系方案。

一、前置准备

1.1 环境要求

操作系统：Linux x86_64 或 ARM64（官方构建基于 musl libc 静态链接，Debian/Ubuntu/RHEL/Alpine 均可直接运行；macOS Apple Silicon 也有官方构建）；
硬件：1 核 1 GB 内存起步即可流畅运行（本机实测内存占用见 6.4 节）；
网络：需要能访问 GitHub Releases 下载安装包（下载受阻时的替代渠道见 1.3 节的 ⚠️ 网络说明）；
端口：默认监听 0.0.0.0:9042，确认未被占用：

ss -ltn | grep 9042

无输出即表示 9042 端口空闲。

1.2 安装 curl 与 tar 工具

Ubuntu Server 最小安装可能缺少下载与解压工具，先补齐：

sudo apt-get update
sudo apt-get install -y curl tar

实测回显（节选）：

Reading package lists... Done
curl is already the newest version (7.81.0-1ubuntu1.21).
tar is already the newest version (1.34+dfsg-1ubuntu0.1.22.04.2).

1.3 下载官方预编译二进制

官方发布件直接挂在 GitHub Releases 上，Linux x86_64 的包名为 liwan-x86_64-unknown-linux-musl.tar.gz，releases/latest/download/ 这个固定路径永远指向最新版：

curl -JLO 'https://github.com/explodingcamera/liwan/releases/latest/download/liwan-x86_64-unknown-linux-musl.tar.gz'
ls -la liwan-*.tar.gz

实测回显：

-rw-r--r-- 1 root root 17967431 Oct 30 02:01 liwan-x86_64-unknown-linux-musl.tar.gz

约 17 MB 的压缩包，解开后是约 49 MB 的单个可执行文件。

⚠️ 网络说明：本实例所在服务器可直连 GitHub Releases 下载（实测全程直连无降级）。若你的网络环境直连 GitHub 失败或速度极慢，可依次尝试：① 镜像加速站拼接下载地址（如 https://gh-proxy.com/https://github.com/...，可用性自行验证）；② 通过自建 HTTP 代理下载（https_proxy=http://<代理地址>:<端口> curl -JLO ...）；③ 从国内可达的其他网络环境下载后 scp 上服务器。安装包官方指纹以 GitHub Releases 页面公示为准。

Linux ARM64 与 macOS 机器只需替换包名：

平台	包名
Linux x86_64	`liwan-x86_64-unknown-linux-musl.tar.gz`
Linux ARM64	`liwan-aarch64-unknown-linux-musl.tar.gz`
macOS Apple Silicon	`liwan-aarch64-apple-darwin.tar.gz`

1.4 解压安装并验证

按官方文档的推荐路径安装到 ~/.local/bin：

mkdir -p ~/.local/bin
tar -xzf liwan-x86_64-unknown-linux-musl.tar.gz -C ~/.local/bin liwan
chmod +x ~/.local/bin/liwan
ls -la ~/.local/bin/liwan

实测回显：

-rwxr-xr-x 1 1001 1001 49143496 Oct 29 21:14 /root/.local/bin/liwan

单个 49,143,496 字节（约 47 MB）的可执行文件，没有第二件东西。把 ~/.local/bin 加入 PATH（写入 shell 配置文件以永久生效）：

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

验证二进制可用：

liwan --help

实测回显：

Usage: liwan [--config <config>] [--log-level <log-level>] [<command>] [<args>]

liwan - lightweight web analytics

Options:
  --config          path to the configuration file
  --log-level       set the log level (default: INFO)
  --help, help      display usage information

Commands:
  generate-config   Save a default configuration file to `liwan.config.toml`
  update-password   Update a user's password
  add-user          Create a new user
  users             List all registered users
  prune             Prune collection data according to current UI-managed
                    settings

注意：Liwan 目前没有 --version 参数，直接运行会报 Unrecognized argument: --version（实测）。版本信息以 GitHub Releases 页面为准，或从启动日志、发布日期判断。

二、首次启动与初始化

2.1 启动服务

前台直接运行即可开始第一次启动：

liwan

实测回显（首次启动完整日志，节选）：

2026-10-30T02:02:21.352159Z  WARN liwan::config: Base URL is not using HTTPS
2026-10-30T02:02:21.395485Z  INFO liwan::app::db: Applied migration: V1__initial
2026-10-30T02:02:21.398663Z  INFO liwan::app::db: Applied migration: V2__remove_indexes
2026-10-30T02:02:21.401182Z  INFO liwan::app::db: Applied migration: V3__utm_params
2026-10-30T02:02:21.406056Z  INFO liwan::app::db: Applied migration: V4__session_intervals
2026-10-30T02:02:21.409293Z  INFO liwan::app::db: Applied migration: V5__screen_size
2026-10-30T02:02:21.412081Z  INFO liwan::app::db: Applied migration: V6__visitor_group_id
2026-10-30T02:02:21.416811Z  INFO liwan::app::db: Applied migration: V7__event_exits
2026-10-30T02:02:21.419113Z  INFO liwan::app::db: Applied migration: V8__event_properties
2026-10-30T02:02:21.422212Z  INFO liwan::web: It looks like you're running Liwan for the first time!
2026-10-30T02:02:21.422222Z  INFO liwan::web: You can get started by visiting: http://localhost:9042/setup?t=lJNNnj8FYc0genMm
2026-10-30T02:02:21.422224Z  INFO liwan::web: To see all available commands, run `liwan --help`

日志里有三类关键信息：

WARN Base URL is not using HTTPS：生产环境建议配置 HTTPS 的 base_url，见《Liwan 1.8 配置参数详解》；
Applied migration: V1..V8：首次启动自动初始化数据库结构；
setup URL：http://localhost:9042/setup?t=<随机令牌>，这是首次初始化的官方入口。

2.2 创建管理员账号（方式一：Web 初始化向导）

用浏览器打开上一步日志里的 setup URL（令牌是随机生成的，以你的日志为准），页面是一个简单的表单：用户名输入框（预填 admin，要求 3 位以上字母数字）与密码输入框（至少 8 位），点击 Finish Setup 即完成管理员创建。本实例创建的账号为：

用户名：admin
密码：q1w2e3r4

初始化完成后 Liwan 会自动跳转到登录页，用该账号登录即可进入看板。

2.3 创建管理员账号（方式二：CLI 命令行）

如果不方便开浏览器（纯终端服务器），也可以停掉服务后用内置 CLI 创建管理员。先停止正在前台运行的服务（Ctrl+C 或 pkill -x liwan），然后：

liwan add-user --admin true admin q1w2e3r4

实测回显：

2026-10-30T02:03:30.598451Z  WARN liwan::config: Base URL is not using HTTPS
User admin created

确认用户已存在：

liwan users

实测回显：

2026-10-30T02:03:30.631287Z  WARN liwan::config: Base URL is not using HTTPS
Users:
 - admin (admin)

两个易踩的坑（均为实测）：

--admin 是带值参数而非开关，必须写 --admin true，直接写 --admin 会报 Error parsing option '--admin' with value 'admin': provided string was not 'true' or 'false'；
CLI 命令与服务进程不能同时运行：服务启动时会持有 DuckDB 文件的写锁，此时执行 add-user 会重试 10 次后报 Could not set lock on file ".../liwan-events.duckdb": Conflicting lock is held in /root/.local/bin/liwan (PID xxxx)。先 systemctl stop liwan（或结束前台进程）再执行 CLI，完事再启动服务。

2.4 启动服务并登录

初始化完成后再次启动：

liwan

实测回显（已无 setup URL）：

2026-10-30T02:03:39.312990Z  WARN liwan::config: Base URL is not using HTTPS
2026-10-30T02:03:39.328002Z  INFO liwan::web: Liwan is running on http://localhost:9042 (0.0.0.0:9042)

浏览器访问 http://<服务器IP>:9042，用 admin / q1w2e3r4 登录。

三、创建项目与站点实体

Liwan 用两个概念组织数据：项目（Project） 是看板与权限的容器，实体（Entity） 是真正接收事件的站点/应用，一个实体可以属于多个项目。本节创建项目 blog 并把同名实体挂进去。

3.1 Web 界面操作

登录后进入 Settings → Projects，点击新建，表单共三处：

ID：blog（项目的路径标识，创建后不可改）；
Display Name：Blog（看板显示名）；
Visibility：Private（仅登录用户可见，另有 Public/Unlisted/Internal 可选）。

保存后再进入 Settings → Entities 新建实体：ID 填 blog，Display Name 填 Blog，并在关联项目中选择刚创建的 blog 项目。

3.2 命令行验证（可选）

习惯用命令行核对结果的话，先用 admin/q1w2e3r4 换取会话 Cookie，再查询列表：

curl -s -c /tmp/cj.txt -X POST http://localhost:9042/api/dashboard/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4"}'
echo
curl -s -b /tmp/cj.txt http://localhost:9042/api/dashboard/entities
echo
curl -s -b /tmp/cj.txt http://localhost:9042/api/dashboard/projects

实测回显：

{"status":"OK"}
{"entities":[{"id":"blog","displayName":"Blog","projects":[{"id":"blog","displayName":"Blog","visibility":"private"}]}]}
{"projects":[{"id":"blog","displayName":"Blog","entities":[{"id":"blog","displayName":"Blog"}],"visibility":"private","hiddenMetrics":[],"hiddenDimensions":["property"],"customEventsHidden":true}]}

四、嵌入追踪脚本并发送第一条流量

4.1 获取追踪脚本标签

Liwan 的追踪脚本由服务端自己托管（版本永远与服务器同步），在 Settings → Entities 中选中实体即可看到嵌入代码，形如：

<script
  type="module"
  src="https://liwan.example.com/script.js"
  data-entity="blog"
></script>

其中 src 换成你的 Liwan 访问地址，data-entity 填实体 ID。脚本服务本身可以先验证：

curl -s -o /dev/null -w "%{http_code} %{size_download}\n" http://localhost:9042/script.js

实测回显：

200 2846

200 状态码、约 2.8 KB 的脚本内容，把这段 <script> 放进目标站点的 <head> 即完成埋点。

4.2 用 curl 模拟一条 pageview

埋点上线前，可以直接向事件接口发请求来验证链路（追踪脚本内部就是发这样的请求）：

curl -s -X POST http://localhost:9042/api/event \
  -H "Content-Type: text/plain;charset=UTF-8" \
  -d '{"name":"pageview","url":"https://blog.example.com/posts/hello-world","entity_id":"blog","referrer":"https://www.google.com/","screen_width":"md","orientation":"landscape"}'

实测回显：

{"status":"OK"}

再补一条首页路径：

curl -s -X POST http://localhost:9042/api/event \
  -H "Content-Type: text/plain;charset=UTF-8" \
  -d '{"name":"pageview","url":"https://blog.example.com/","entity_id":"blog"}'

实测回显：

{"status":"OK"}

本实例累计发送了 4 条不同路径/来源的 pageview 用于看板验证。

4.3 看板数据验证

浏览器打开 http://<服务器IP>:9042，进入 blog 项目，应能看到实时访客数与图表刷新。命令行可以用报表接口做同等验证（同样用 3.2 节的会话 Cookie）：

curl -s -b /tmp/cj.txt -X POST http://localhost:9042/api/dashboard/project/blog/stats \
  -H "Content-Type: application/json" \
  -d '{"range":{"start":"2026-10-23T00:00:00.000Z","end":"2026-10-30T23:59:59.000Z"},"filters":[],"event":"pageview"}'

实测回显：

{"currentVisitors":4,"stats":{"totalViews":4,"uniqueVisitors":4,"bounceRate":null,"avgTimeOnSite":null},"statsPrev":{"totalViews":0,"uniqueVisitors":0,"bounceRate":null,"avgTimeOnSite":null}}

totalViews: 4 说明 4 条测试事件全部入库。页面维度报表：

curl -s -b /tmp/cj.txt -X POST http://localhost:9042/api/dashboard/project/blog/dimension \
  -H "Content-Type: application/json" \
  -d '{"dimension":"path","range":{"start":"2026-10-23T00:00:00.000Z","end":"2026-10-30T23:59:59.000Z"},"filters":[],"metric":"views","event":"pageview"}'

实测回显：

{"data":[{"dimensionValue":"/","value":1.0,"displayName":null,"icon":null},{"dimensionValue":"/posts/hello-world","value":3.0,"displayName":null,"icon":null}]}

来源维度报表（验证 referrer 采集）：

curl -s -b /tmp/cj.txt -X POST http://localhost:9042/api/dashboard/project/blog/dimension \
  -H "Content-Type: application/json" \
  -d '{"dimension":"referrer","range":{"start":"2026-10-23T00:00:00.000Z","end":"2026-10-30T23:59:59.000Z"},"filters":[],"metric":"views","event":"pageview"}'

实测回显：

{"data":[{"dimensionValue":"Unknown","value":2.0,"displayName":null,"icon":null},{"dimensionValue":"google.com","value":3.0,"displayName":"Google","icon":"google"}]}

至此「安装 → 初始化 → 建站 → 埋点 → 看到数据」的完整闭环已经打通。

五、配置 systemd 开机自启

生产环境不要用前台进程跑服务，官方文档给出了 systemd 单元模板。创建 /etc/systemd/system/liwan.service：

sudo tee /etc/systemd/system/liwan.service > /dev/null <<'EOF'
[Unit]
Description=liwan web analytics
After=network.target

[Service]
ExecStart=/root/.local/bin/liwan
Restart=on-failure
User=root

[Install]
WantedBy=multi-user.target
EOF

提示：User 与 ExecStart 路径按实际部署调整。若希望以普通用户运行，把二进制放到该用户可读的路径（如 /home/yourusername/.local/bin/liwan），并将 User=yourusername；以非 root 运行时注意数据目录默认在 $HOME/.local/share/liwan/data，属主要一致。更细的运行参数（监听地址、数据目录）见《Liwan 1.8 配置参数详解》。

加载并启用：

sudo systemctl daemon-reload
sudo systemctl enable liwan
sudo systemctl start liwan

实测回显（enable 一步）：

Created symlink /etc/systemd/system/multi-user.target.wants/liwan.service -> /etc/systemd/system/liwan.service.

确认状态：

systemctl status liwan --no-pager -n 0

实测回显：

* liwan.service - liwan web analytics
     Loaded: loaded (/etc/systemd/system/liwan.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-30 02:13:39 UTC; 4s ago
   Main PID: 3511 (liwan)
      Tasks: 20 (limit: 2266)
     Memory: 28.1M

常驻运行下内存占用 28 MB 量级（cgroup 统计口径；ps -eo rss,comm 显示进程 RSS 约 57 MB），单核即可胜任中小流量。查看运行日志：

journalctl -u liwan --no-pager -n 4

实测回显：

Oct 30 02:13:39 liwan-server systemd[1]: Started liwan web analytics.
Oct 30 02:13:39 liwan-server liwan[3511]: 2026-10-30T02:13:39.093545Z  WARN liwan::config: Base URL is not using HTTPS
Oct 30 02:13:39 liwan-server liwan[3511]: 2026-10-30T02:13:39.110625Z  INFO liwan::web: Liwan is running on http://localhost:9042 (0.0.0.0:9042)

systemd 的日常操作（重启、开机自启管理、日志排障、数据备份与版本升级）在《Liwan 1.8 运维实操指南》中有完整实操手册。

六、安装后检查清单与常见问题

6.1 安装结果自查

检查项	命令	期望结果
二进制可执行	`liwan --help`	打印 Usage 与 5 个子命令
服务存活	`systemctl is-active liwan`	`active`
端口监听	`ss -ltn	grep 9042`
Web 可访问	`curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9042/`	`200`
追踪脚本	`curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9042/script.js`	`200`
事件接口	4.2 节的 curl POST	`{"status":"OK"}`

6.2 WARN: Base URL is not using HTTPS

每次启动都会出现这条警告，意思是当前配置的 base_url 是 http。测试环境可忽略；生产环境给 Liwan 套上反向代理与 TLS 证书后，把 base_url 改为 https 地址即可消除（配置方法见《Liwan 1.8 配置参数详解》，反向代理与真实客户端 IP 的透传配置见《Liwan 1.8 运维实操指南》）。

6.3 CLI 报 DuckDB 数据库被锁

报错形如（实测）：

Error: Failed to load DuckDB Database after 10 attempts

Caused by:
    0: IO Error: Could not set lock on file "/root/.local/share/liwan/data/liwan-events.duckdb": Conflicting lock is held in /root/.local/bin/liwan (PID 2674). See also https://duckdb.org/docs/stable/connect/concurrency

原因：DuckDB 是单写者引擎，服务进程持有写锁期间，add-user/users/prune 等 CLI 命令无法打开同一库文件。处理：先 systemctl stop liwan，执行完 CLI 后再 systemctl start liwan。

6.4 忘记管理员密码

用 CLI 重置（同样需要先停服务）：

liwan update-password admin <新密码>

6.5 升级版本

下载新版 tar.gz 解压覆盖 ~/.local/bin/liwan，然后 systemctl restart liwan。启动日志中的 Applied migration 序列会自动完成库结构迁移。升级前建议先按《Liwan 1.8 运维实操指南》备份数据目录；跨 minor 版本（如 1.7 → 1.8）前先读官方 Releases 说明，v1.8.0 就包含团队权限与 npm 包名的破坏性变更。