Ubuntu 22.04 安装 Offen 1.4.2 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装并跑通 Offen Fair Web Analytics v1.4.2——覆盖官方 deb 包与 tar.gz 单二进制两种安装方案、完整性校验、/etc/offen/offen.env 配置、systemd 托管启动、首次账户创建（offen setup）与 Web 端点验证。全文命令与回显均为 2026-10-30 在 Ubuntu 22.04.5 LTS 环境实测记录。

一、环境信息

本指南实测环境与软件版本如下：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64，PRETTY_NAME="Ubuntu 22.04.5 LTS"）
• 软件版本：Offen v1.4.2（官方当前最新正式版，GitHub Releases Atom 查询于 2026-10-30）
• 安装位置：二进制 /usr/local/bin/offen，配置 /etc/offen/offen.env，默认数据库 /var/opt/offen/offen.db
• systemd 服务：offen.service（deb 包附带；tar.gz 方案按第四/五节给出的单元文件自建）
• 监听端口：本指南实验路径使用 OFFEN_SERVER_PORT="8080" 直连验证；生产域名形态使用 80/443（AutoTLS）
• 依赖：无强制外部依赖（默认内嵌 SQLite）；如外接 MySQL/PostgreSQL 见 《Offen 1.4.2 配置参数详解》第七章

工具定位与选型背景见 《Offen 介绍与选型指南》。

二、前置条件

安装开始前确认以下条件满足：

1. 具备 sudo 权限的 root 或普通用户：本文命令以 root 直接执行（root 下无需 sudo 前缀）。
2. 基础工具：curl 与 tar 需已安装。最小化安装的系统先补齐：

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

3. 网络可达发行渠道：需要访问 get.offen.dev（官方下载跳转服务）。⚠️ 网络说明：2026-10-30 实测直连 get.offen.dev 正常可用（无需代理）；若你的网络环境无法直连，请自行配置 HTTP 代理后重试。
4. 端口规划：
   • 实验直连形态：任选一个空闲 TCP 端口（本文用 8080）；
   • 生产域名形态：80 与 443 必须对公网开放（AutoTLS 需要它们申请与续期证书，官方 "Installation on Ubuntu" 页明示）。
5. （可选）生产域名 DNS：如使用 AutoTLS，需有一个解析到本机的域名（本文示例 offen.example.com）。

⚠️ 注意：Offen 官方要求实例以 HTTPS 提供服务（AutoTLS 或自带证书均可）。直连 HTTP 形态仅建议用于内网验证与本文的快速跑通；给站点正式采集前请切换到第七章 7.3 的 AutoTLS 形态。

三、版本选型说明

Offen 发布渠道有三条（官方 "Downloads and distributions" 页）：

本指南安装 v1.4.2——写作时点的最新正式版。版本历史（GitHub Releases Atom，查询 2026-10-30）：v1.4.2（2024-05-22）、v1.4.1（2024-05-17）、v1.4.0（2024-05-01）、v1.3.4（2022-12-01）及更早的 v1.2.x–v1.3.x 系列。

安装后用以下命令确认版本，实测回显：

offen version

time="2026-10-30T01:13:14Z" level=info msg="Binary built using" revision=v1.4.2

四、方案 A：官方 deb 包安装（Ubuntu/Debian 适用）

4.1 方案说明

官方自 v0.1.6 起提供 deb 包，包内自带三样东西：/usr/local/bin/offen 二进制、/etc/offen/offen.env 配置模板、offen.service systemd 单元——安装即完成托管配置，是 Ubuntu 上最省事的方案。本方案全程实测通过。

4.2 下载 deb 包

cd /root && curl -sSL https://get.offen.dev/deb -o offen.deb

实测下载结果：exit=0，文件大小 10465996 字节（约 10 MB）。

4.3 安装

dpkg -i /root/offen.deb

实测回显：

Selecting previously unselected package offen.
(Reading database ... 7312 files and directories currently installed.)
Preparing to unpack /root/offen.deb ...
Unpacking offen (1.4.2) ...
Setting up offended (1.4.2) ...

⚠️ 注意：上文中 "Setting up offended" 为实测回显的逐字照录（dpkg 输出如此，非笔误），实际生效的包名为 offen。

官方还提供 GPG 签名验证（dpkg-sig --verify offen.deb），实测当前环境无法完成：dpkg-sig 工具默认未安装，且官方文档给出的公钥源（keybase hioffen）实测失效——详见第九章 FAQ Q3。deb 包完整性可先用 md5 校验兜底（方案 B 的 checksums.txt 思路同理）。

4.4 验证安装

which offen
offen version

实测回显：

/usr/local/bin/offen
time="2026-10-30T01:13:14Z" level=info msg="Binary built using" revision=v1.4.2

再看包落位的文件清单：

dpkg -L offen | grep -E "bin|env|service"

实测回显：

/usr/local/bin/offen
/etc/offen
/etc/offen/offen.env
/lib/systemd/system/offen.service

三件套齐了：二进制、配置模板、systemd 单元。清理安装包：

rm /root/offen.deb

五、方案 B：官方 tar.gz 单二进制安装（任意 Linux）

5.1 方案说明

官方 tar.gz 打包了全部支持平台的二进制（Linux amd64/arm64/arm-v7、macOS、Windows），适合 Debian 系之外的 Linux 或不想到处留包管理器痕迹的服务器。本方案在同一台 Ubuntu 22.04.5 上实测通过：下载 → md5 校验 → 落位 /usr/local/bin → 复用 systemd 单元启动。

5.2 下载与完整性校验

mkdir -p /opt/offen && cd /opt/offen
curl -sSL https://get.offen.dev -o offen.tar.gz

实测下载 50262606 字节（约 48 MB，含全平台二进制）。解压：

tar -xzf offen.tar.gz && ls -la

实测回显（输出节选）：

-rw-r--r-- 1 1001 1002    11357 May 22  2024 LICENSE
-rw-r--r-- 1 1001 1002     9015 May 22  2024 NOTICE
-rw-r--r-- 1 1001 1002     9167 May 22  2024 README.md
-rw-r--r-- 1 1001 1002      288 May 22  2024 checksums.txt
-rwxr-xr-x 1 1001 1002 27593944 May 22  2024 offen-darwin-10.12-amd64
-rwxr-xr-x 1 1001 1002 28123944 May 22  2024 offen-linux-amd64
-rw-r--r-- 1 1001 1002      659 May 22  2024 offen-linux-amd64.asc
-rwxr-xr-x 1 1001 1002 26635532 May 22  2024 offen-linux-arm-v7
-rwxr-xr-x 1 1001 1002 26849048 May 22  2024 offen-linux-arm64
-rwxr-xr-x 1 1001 1002 27875840 May 22  2024 offen-windows-4.0-amd64.exe

做完整性校验——checksums.txt 是 md5 清单，直接用 md5sum -c：

md5sum -c checksums.txt

实测回显：

./offen-linux-arm64: OK
./offen-linux-arm-v7: OK
./offen-windows-4.0-amd64.exe: OK
./offen-darwin-10.12-amd64: OK
./offen-linux-amd64: OK

五个文件全部 OK。

⚠️ 注意：官方文档主推 GPG 签名验证（.asc 文件随包附带），但实测公钥获取失败（FAQ Q3），因此本指南以 md5 校验作为实测可行的完整性手段。GPG 验签的实测现象：gpg --verify offen-linux-amd64.asc offen-linux-amd64 能识别出签名（Signature made Wed May 22 18:28:40 2024 UTC using RSA key F20D4074068C636D58B53F46FD60FBEDC90B8DA1），但报 Can't check signature: No public key——签名真实存在，只是公钥源失效导致验不下去。

5.3 安装到系统路径

把目标平台的二进制复制到 PATH 内并加执行位（本文主机是 x86_64 Linux，选 offen-linux-amd64）：

cp /opt/offen/offen-linux-amd64 /usr/local/bin/offen
chmod +x /usr/local/bin/offen
offen version

实测回显：

time="2026-10-30T01:41:29Z" level=info msg="Binary built using" revision=v1.4.2

5.4 systemd 服务单元

tar.gz 方案不自带单元文件，自建 /etc/systemd/system/offen.service（内容与 deb 包附带的单元一致，仅 ExecStart 指向同一标准路径）：

[Unit]
Description=Offen Web Analytics

[Service]
ExecStart=/usr/local/bin/offen
Restart=always

[Install]
WantedBy=multi-user.target

逐项说明：ExecStart 直接运行 offen（无参数即 serve，读取 /etc/offen/offen.env 等位置的配置）；Restart=always 保证进程崩溃后自动拉起；WantedBy=multi-user.target 使服务随系统启动。加载单元：

systemctl daemon-reload

5.5 验证安装

systemctl start offen
systemctl is-active offen

实测回显：

active

六、方案对比与选择建议

选择建议：Ubuntu/Debian 服务器无脑选方案 A——托管、配置模板、升级、卸载都由包管理器接管；非 Debian 系、或希望把二进制放进自定义路径（如 /opt）的场景选方案 B。两方案安装的二进制完全同源，配置与后续运维完全一致。

七、配置说明（两方案共用）

7.1 配置文件位置与查找顺序

Offen 运行时配置来自环境变量或 env 文件（OFFEN_<scope>_<key> 命名，逐项含义见 《Offen 1.4.2 配置参数详解》）。env 文件的查找顺序（offen serve -h 原文）：

1. -envfile 参数显式指定的文件；
2. 未指定时依次找 offen.env：当前工作目录 → ~/.config → $XDG_CONFIG_HOME → /etc/offen。

deb 包方案 /etc/offen/offen.env 已自动创建；tar.gz 方案按同样路径创建即可。

7.2 本指南实测配置（8080 端口 + SQLite）

实测写入 /etc/offen/offen.env 的内容：

OFFEN_SECRET="DwNCkfF3vmJSOfTxCBiWTQ=="
OFFEN_SERVER_PORT="8080"
OFFEN_DATABASE_DIALECT="sqlite3"
OFFEN_DATABASE_CONNECTIONSTRING="/var/opt/offen/offen.db"
OFFEN_APP_LOCALE="en"

逐项说明：OFFEN_SECRET 由 offen secret -quiet 生成（16 字节 Base64 随机值，用于签名登录 cookie 与 URL token；不设置则每次重启随机生成，所有会话失效）；OFFEN_SERVER_PORT 改默认的 3000 为 8080（避开本机已占端口）；OFFEN_DATABASE_DIALECT/OFFEN_DATABASE_CONNECTIONSTRING 显式落 SQLite 文件路径（这本就是默认值，写出来便于复查）；OFFEN_APP_LOCALE 设 en——实测设 zh 会直接 fatal（FAQ Q2）。

密钥生成的实测命令与回显：

offen secret -quiet

DwNCkfF3vmJSOfTxCBiWTQ==

7.3 生产域名配置（AutoTLS，官方推荐形态）

给正式站点采集时，用 AutoTLS 让 offen 自管证书（需域名解析到本机、80/443 公网可达）：

OFFEN_SECRET="DwNCkfF3vmJSOfTxCBiWTQ=="
OFFEN_SERVER_AUTOTLS="offen.example.com"
OFFEN_SMTP_HOST="smtp.example.com"
OFFEN_SMTP_SENDER="offen-noreply@example.com"
OFFEN_SMTP_USER="offen"
OFFEN_SMTP_PASSWORD="q1w2e3r4"
OFFEN_DATABASE_DIALECT="sqlite3"
OFFEN_DATABASE_CONNECTIONSTRING="/var/opt/offen/offen.db"
OFFEN_APP_LOCALE="en"

⚠️ 注意：设置 OFFEN_SERVER_AUTOTLS 后，OFFEN_SERVER_PORT 被忽略，进程改听 80 与 443（官方文档 Heads Up 原文）。SMTP 四项用于邀请用户与重置密码邮件；不配则回退本机 sendmail 且可靠性差（官方原文），强烈建议配置。证书缓存默认 /var/www/.cache，务必保持该目录持久化，否则每次请求都会触发签发、很快被 Let's Encrypt 限流。上述域名与 SMTP 值为示例形态（AutoTLS 因需要公网域名，本机实验路径未实跑；行为依据官方配置文档）。

7.4 配置校验

改完配置先别启动，用 offen debug 打印当前生效配置：

offen debug

实测回显（输出节选，完整 JSON 含 Secret 字段）：

time="2026-10-30T01:13:44Z" level=info msg="Current configuration values"
{
  "Server": {
    "Port": 8080,
    "ReverseProxy": false,
    "SSLCertificate": "",
    "SSLKey": "",
    "AutoTLS": null,
    "LetsEncryptEmail": "",
    "CertificateCache": "/var/www/.cache"
  },
  "Database": {
    "Dialect": "sqlite3",
    "ConnectionString": "/var/opt/offen/offen.db",
    "ConnectionRetries": 0
  },
  "App": {
    "Development": false,
    "LogLevel": 4,
    "SingleNode": true,
    "Locale": "en",
    "RootAccount": "",
    "DemoAccount": "",
    "DeployTarget": "",
    "Retention": {}
  },
  "Secret": "DwNCkfF3vmJSOfTxCBiWTQ==",
  "SMTP": {
    "Authtype": "LOGIN",
    "User": "",
    "Password": "",
    "Host": "",
    "Port": 587,
    "Sender": "no-reply@offen.dev"
  }
}

确认 Port、Database、Locale 与预期一致即可启动。

八、启动服务与首次配置

8.1 systemd 托管启动

systemctl enable offen
systemctl start offen

实测回显（enable）：

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

状态确认：

systemctl status offen --no-pager

实测回显：

* offen.service - Offen Web Analytics
     Loaded: loaded (/lib/systemd/system/offen.service; enabled; vendor preset: enabled)
     Active: active (running) since Fri 2026-10-30 01:13:49 UTC; 2s ago
   Main PID: 2840 (offen)
      Tasks: 8 (limit: 2266)
     Memory: 6.6M
        CPU: 17ms
     CGroup: /system.slice/offen.service
             `-2840 /usr/local/bin/offen

注意 Memory: 6.6M——单二进制 + SQLite 的资源占用极低。服务日志走 journald：

journalctl -u offen --no-pager

实测回显（首次启动段）：

Oct 30 01:13:49 offen-server systemd[1]: Started Offen Web Analytics.
Oct 30 01:13:49 offen-server offen[2840]: time="2026-10-30T01:13:49Z" level=warning msg="SMTP for transactional email is not configured right now, mail delivery will be unreliable"
Oct 30 01:13:49 offen-server offen[2840]: time="2026-10-30T01:13:49Z" level=warning msg="Refer to the documentation to find out how to configure SMTP"
Oct 30 01:13:49 offen-server offen[2840]: time="2026-10-30T01:13:49Z" level=info msg="Successfully applied database migrations"
Oct 30 01:13:49 offen-server offen[2840]: time="2026-10-30T01:13:49Z" level=info msg="Server now listening on port 8080"
Oct 30 01:13:49 offen-server offen[2840]: time="2026-10-30T01:13:49Z" level=info msg="Cron successfully pruned expired events" removed=0

三条 info 对应三件启动事务：迁移已应用、端口已监听、过期清理 cron 已跑。SMTP warning 在配置 7.3 的 SMTP 后消失。

8.2 创建管理员账户（offen setup）

服务跑起来后，用 CLI 创建首个管理员与账户（邮箱 admin@example.com、密码 q1w2e3r4 为本文演示账号）：

offen setup -email admin@example.com -name "Demo Site" -password q1w2e3r4

实测回显：

time="2026-10-30T01:14:01Z" level=info msg="Using command line arguments to create seed account user and account"
time="2026-10-30T01:14:02Z" level=info msg="Successfully created account Demo Site with ID 5e00fe8d-cf71-4226-9c7e-37ccc5195145, you can use the given credentials to access it"

返回的 Account ID（5e00fe8d-cf71-4226-9c7e-37ccc5195145）是嵌入脚本的 account_id 参数，记下来。不想在命令行明文传密码时，去掉 -password 让命令交互式提示输入（offen setup -h 原文：input is not displayed）；-populate 参数可在配置缺密钥时自动生成并写回 env 文件。setup 只需执行一次，重复执行会因数据已存在而要求 -force（会删数据，慎用）。

8.3 Web 页面验证

逐个验证关键端点（8080 为 7.2 实验配置的端口；生产 AutoTLS 形态对应 443）：

for p in / /login/ /setup/ /auditorium/ /vault "/script.js?account_id=5e00fe8d-cf71-4226-9c7e-37ccc5195145"; do
  echo -n "$p -> "
  curl -s -o /dev/null -w '%{http_code} %{content_type}\n' "http://localhost:8080$p"
done

实测回显：

/ -> 200 text/html; charset=utf-8
/login/ -> 200 text/html; charset=utf-8
/setup/ -> 200 text/html; charset=utf-8
/auditorium/ -> 200 text/html; charset=utf-8
/vault -> 200 text/html; charset=utf-8
/script.js?account_id=5e00fe8d-cf71-4226-9c7e-37ccc5195145 -> 200 text/javascript; charset=utf-8

六个端点全部 200：首页、登录页、初始配置页、分析面板 SPA、加密代理页（vault，采集链路的隐藏 iframe 目标）、以及该账户的采集脚本。浏览器打开 http://<服务器IP>:8080/login/，用 admin@example.com / q1w2e3r4 登录即可进入 Auditorium；把面板给出的嵌入代码加进你的站点页面：

<script src="http://offen.example.com/script.js?account_id=5e00fe8d-cf71-4226-9c7e-37ccc5195145"></script>

访客点击横幅 "I allow" 同意后，数据开始入库。想先零配置看看面板长什么样，跑 offen demo -port 8131 -users 120（实测生成 1313 条模拟事件，访问 http://localhost:8131/intro/，演示账号 demo@offen.dev / demo），详见 《Offen 1.4.2 常用 CLI 命令与工具详解》 demo 小节。

💡 说明：采集脚本在宿主页面注入一个指向 /vault 的隐藏 iframe，并在浏览器端完成事件加密后才上报——这就是"同意前不发数据、服务端只见密文"的机制来源；consent 横幅的按钮文案为 "I allow" / "I don't allow"（实测 DOM）。对比"从服务器日志做统计"的无侵入路线可看 《GoAccess 安装指南》。

九、常见问题（FAQ）

Q1：访问 /script.js 返回 404？ 确认 URL 带上了 account_id 参数且值正确（setup 回显里的 UUID）。实测同一路径不带参数返回的也是 200，但脚本内容里的账户配置为空、无法采集；账户 ID 错误时脚本会加载但 vault 侧无法匹配账户。用 offen debug 与数据库 accounts 表核对账户 ID。

Q2：启动失败，日志报 unknown or unsupported locale zh？ OFFEN_APP_LOCALE 只支持 en/de/fr/es/pt/vi（官方配置文档），实测填 zh 直接 fatal 退出：

time="2026-10-30T01:13:36Z" level=fatal msg="Error sourcing runtime configuration" error="config: error processing configuration: envconfig.Process: assigning OFFEN_APP_LOCALE to Locale: converting 'zh' to type config.Locale. details: unknown or unsupported locale zh"

改成 OFFEN_APP_LOCALE="en"（或其他五种之一）后重启即可。

Q3：GPG 签名验证不过，报 Can't check signature: No public key？ 官方文档让从 https://keybase.io/hioffen/pgp_keys.asc 导入公钥，实测该地址返回 32 字节的 SELF-SIGNED PUBLIC KEY NOT FOUND（keybase 侧已无此钥）；备用源 keys.openpgp.org 按指纹 F20D4074068C636D58B53F46FD60FBEDC90B8DA1 检索同样为空。签名本身有效（gpg 能读出签名时间与密钥指纹），只是无处取公钥。实测可行的替代方案：用随包的 checksums.txt 做 md5 校验（回显见 5.2，全部 OK）。deb 包同理可用 dpkg 校验已安装文件：dpkg -V offen（无输出即未篡改）。

Q4：dpkg -i 报依赖错误？ offen 的 deb 依赖极少（实测全新 Ubuntu 最小环境一次通过）。若出现依赖报错，先 apt-get update && apt-get -f install 修复依赖链，再重新 dpkg -i。

Q5：生产环境监听 80/443 失败？ AutoTLS 形态下进程必须能绑定 80 与 443。检查端口占用（ss -ltnp | grep -E ':80 |:443 '）与 CAP_NET_BIND_SERVICE 权限；非 root 运行时可用 AmbientCapabilities=CAP_NET_BIND_SERVICE 单元属性放行。

Q6：忘了 admin 密码怎么办？ 配置好 SMTP 后在 /login/ 页走 "Forgot password?" 流程；SMTP 未配置时该流程不可用，只能重建实例数据（offen setup -force，会清空既有事件与账户，慎用）。

十、卸载与清理

方案 A（deb）卸载：

systemctl stop offen
systemctl disable offen
dpkg -r offen

实测回显（disable）：

Removed "/etc/systemd/system/multi-user.target.wants/offen.service".

方案 B（tar.gz）卸载（无包管理器记录，手动清三处）：

systemctl stop offen
systemctl disable offen
rm /etc/systemd/system/offen.service
systemctl daemon-reload
rm /usr/local/bin/offen
rm -rf /opt/offen

两方案的数据残留同处清理（卸载后确认不再需要再删）：

rm -rf /var/opt/offen /etc/offen /var/www/.cache

十一、参考链接

• 官方安装教程（Ubuntu）：https://docs.offen.dev/running-offen/tutorials/configuring-deploying-offen-ubuntu/
• 安装要求（SSL/存储/反代/邮件）：https://docs.offen.dev/running-offen/installation-requirements/
• 下载与发行渠道：https://docs.offen.dev/running-offen/downloads-distributions/
• 配置参考：https://docs.offen.dev/running-offen/configuring-the-application/
• 命令参考：https://docs.offen.dev/running-offen/using-the-command/
• 代码仓库：https://github.com/offen/offen
• 本站相关篇章：《Offen 介绍与选型指南》、《Offen 1.4.2 配置参数详解》、《Offen 1.4.2 常用 CLI 命令与工具详解》、《GoAccess 安装指南》、《Umami Docker Compose 部署指南》