Offen 1.4.2 常用 CLI 命令与工具详解

Offen 1.4.2 单二进制 CLI 全量详解：serve/setup/secret/version/debug/migrate/expire/demo 八个入口的参数表与真实回显、重复 setup 与短密码 fatal 实录、demo 一次性实例与临时库生命周期实测，附单节点/多节点例行事务分工表。

OffenOffen监控2026/10/30

Offen 1.4.2 常用 CLI 命令与工具详解

目标：把 Offen Fair Web Analytics v1.4.2 单二进制 offen 的全部命令入口一次讲全——无参启动（serve）与 setup、secret、version、debug、migrate、expire、demo 七个子命令的参数表、典型用法与真实回显，并给出单节点/多节点两种模式下例行事务（迁移与过期清理）的分工建议。全文命令与回显均为 2026-10-30 在 Ubuntu 22.04.5 LTS + Offen v1.4.2 环境实测记录。

一、环境信息

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

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64，PRETTY_NAME="Ubuntu 22.04.5 LTS"）
  • 软件版本：Offen v1.4.2（offen version 回显 revision=v1.4.2，见 4.4）
  • 二进制位置：/usr/local/bin/offen（安装过程见 《Ubuntu 22.04 安装 Offen 1.4.2 指南》）
  • 配置文件：/etc/offen/offen.env（内容见各子命令实测处引用）
  • systemd 服务：offen.service（systemctl is-active 返回 active）
  • 监听端口：8080；SQLite 数据库 /var/opt/offen/offen.db
  • 演示账户：admin@example.com / q1w2e3r4（安装篇 offen setup 创建，Account ID 5e00fe8d-cf71-4226-9c7e-37ccc5195145）

二、工具概览

Offen 只发行一个二进制 offen，所有能力都通过它的子命令提供。offen -h 打印入口清单（无参数运行等价于 offen serve，即启动 Web 服务）：

offen -h

实测回显：


"offen" makes the following subcommands available:

- "serve" runs the application (this will also run when not providing a subcommand)
- "setup" can be used to setup a new instance
- "secret" can be used to generate runtime secrets
- "demo" starts an ephemeral instance for testing
- "expire" prunes expired events from the database
- "migrate" applies pending database migrations
- "debug" prints the currently applied configuration values

Refer to the -help content of each subcommand for information about how to use
them. Further documentation is available at
https://docs.offen.dev/running-offen/using-the-command/

入口总览（每个子命令都支持 -help 查看用法、-envfile 指定配置文件）：

命令用途生产使用频率
（无参）/ serve启动 Web 服务，读取配置监听每次开机（由 systemd 托管）
setup初始化数据库并创建首个账户与用户仅首次（重建时配合 -force）
secret生成 Base64 随机密钥配置时一次性
version打印二进制构建版本排障/升级核对
debug打印当前生效配置改配置后预检
migrate应用数据库迁移仅多节点模式手动执行
expire清理过期事件仅多节点模式手动执行
demo起一个带模拟数据的一次性实例体验/演示

子命令拼写错误不会执行任何操作，直接报错并回显清单：

offen foobar

实测回显（首行）：

Error: unknown subcommand "foobar"

（随后重复 offen -h 的入口清单，此处略。）

三、前置条件

  1. 二进制在 PATH 内：which offen 返回 /usr/local/bin/offen（安装见 《Ubuntu 22.04 安装 Offen 1.4.2 指南》）。本篇所有命令均可独立执行，不依赖特定托管方式。
  2. 一份可用配置：serve/setup/migrate/expire/debug 都要读配置（env 文件查找顺序与优先级实测见 《Offen 1.4.2 配置参数详解》第三章）；本篇基线配置为安装篇写入的 /etc/offen/offen.env。
  3. 权限：写 /etc/offen、/var/opt/offen 与 systemd 操作需要 root 或对应权限；本篇命令以 root 直接执行。

四、各子命令详解

4.1 serve：启动 Web 服务

serve 启动 HTTP 服务并监听配置的端口，是生产部署的常驻形态；不带任何子命令运行 offen 与 offen serve 完全等价（offen -h 原文 "this will also run when not providing a subcommand"）。参数只有一个：

Usage of "serve":
  -envfile string
    	the env file to use

-envfile 显式指定配置文件，不给则走默认查找级联（offen serve -h 原文：当前工作目录 → ~/.config → $XDG_CONFIG_HOME → /etc/offen；级联优先级实测见配置篇 3.2）。前台启动一个实例观察启动日志：

: > /tmp/empty.env
env OFFEN_SERVER_PORT="8099" offen serve -envfile /tmp/empty.env > /tmp/rp.log 2>&1 &
sleep 4
head -5 /tmp/rp.log
kill %1

实测回显（实例使用空配置，监听 8099）：

time="2026-10-30T01:57:41Z" level=warning msg="SMTP for transactional email is not configured right now, mail delivery will be unreliable"
time="2026-10-30T01:57:41Z" level=warning msg="Refer to the documentation to find out how to configure SMTP"
time="2026-10-30T01:57:41Z" level=info msg="Successfully applied database migrations"
time="2026-10-30T01:57:41Z" level=info msg="Server now listening on port 8099"
time="2026-10-30T01:57:41Z" level=info msg="Cron successfully pruned expired events" removed=0

五条日志对应四件事：SMTP 未配置警告两条（消除方法见配置篇 5.3）、数据库迁移自动应用（单节点模式内置行为，4.6）、端口监听、内置 cron 完成一轮过期清理（4.7）。systemd 托管下的同款日志经 journald 查看，回显见安装篇 8.1。

4.2 setup：初始化实例并创建首个账户

setup 负责把配置指向的数据库初始化（建表 + 种子数据）并创建首个账户用户。offen setup -h 全文：


"setup" is used to populate a fresh Offen instance with user(s) and account(s).
In the most basic case, you are likely going to create a single user and an
account will then use the UI to add more users create additional accounts.

A basic example for setting up a new instance looks like:

$ offen setup -name "My New Account" -email me@mydomain.org -populate

The command will then prompt for a password to use. Passing -populate will
create potentially missing secrets in your envfile. Do not pass the flag if you
plan to do this yourself.

If you do not want to use the CLI, you can also create an initial account and
user by visting "/setup/" in your browser while the Offen instance is running.

Usage of "setup":
  -email string
    	the email address used for login
  -envfile string
    	the env file to use
  -force
    	allow setup to delete existing data
  -forceid string
    	force usage of given valid UUID as account ID (this is meant to be used in tests or similar - you probably do not want to use this)
  -name string
    	the account name
  -password string
    	the password used for login (must be at least 8 characters long)
  -populate
    	in case required secrets are missing from the configuration, create and persist them in the target env file
  -source string
    	a configuration file (this is an experimental feature - do not use it if you are not sure)

参数逐个说明：

  • -email / -name / -password：登录邮箱、账户名、密码；密码至少 8 位（不足的实测报错见 FAQ Q2）。不给 -password 时命令会交互式提示输入（-h 原文：input is not displayed），避免密码进 shell 历史。
  • -populate：配置缺密钥时自动生成并写回 env 文件（配合 4.3 的 secret 使用可全自动初始化）。
  • -force：允许删除既有数据后重建——仅在明确要清空实例时使用。
  • -forceid：强制指定账户 UUID，官方注明仅供测试。
  • -source：实验性配置来源参数，官方注明不确定就别用。
  • 不走 CLI 时，服务运行中访问浏览器 /setup/ 页可完成同样的初始化。

创建首个账户的标准用法（邮箱/密码为演示账号；成功回显为安装篇 8.2 同环境实测）：

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 就是嵌入脚本的 account_id 参数（嵌入方法见 《Offen 介绍与选型指南》第五章）。setup 只需成功执行一次；对已有数据重复执行会被拒绝，实测：

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

实测回显：

time="2026-10-30T01:59:21Z" level=info msg="Using command line arguments to create seed account user and account"
time="2026-10-30T01:59:21Z" level=fatal msg="Error bootstrapping database" error="persistence: action would overwrite existing data - not allowed"

需要重建时加 -force（先备份数据库文件，它会清掉既有事件与账户）。

4.3 secret：生成运行时密钥

secret 生成 Base64 编码的随机密钥，供 OFFEN_SECRET 等配置项使用（该参数的作用与"不固定会怎样"见配置篇 5.4）。offen secret -h 全文：


"secret" can be used to generate Base64-encoded random secrets for signing
cookies or similar. The default length of 16 is a good default value for
generating a value to use as OFFEN_SECRET. Pass '-quiet' to print a single secret
to stdout (this can be used when creating config files for example).

Usage of "secret":
  -count int
    	the number of secrets to generate (default 1)
  -length int
    	the secret's length in bytes (default 16)
  -quiet
    	only print secrets to stdout

默认形态（info 日志 + 密钥同行输出）：

offen secret

实测回显：

time="2026-10-30T01:59:02Z" level=info msg="Created 16 bytes secret" secret="uQIvGyyZFWoX8pCb68D8eg=="

-quiet 只打印密钥本身，适合直接接进配置文件生成脚本（安装篇 7.2 即此用法）：

offen secret -quiet

实测回显：

dgKP6sKujuPz6vLD+uN2bA==

-count 与 -length 控制数量与字节长度（官方：默认 16 字节是配置应用所需密钥的良好默认值）：

offen secret -count 2 -length 32

实测回显：

time="2026-10-30T01:59:02Z" level=info msg="Created 32 bytes secret" secret="ja4d22nIEeBJpgDrvczeiz24011Hd4o4Fk0vQxKem6s="
time="2026-10-30T01:59:02Z" level=info msg="Created 32 bytes secret" secret="IxWWWkJe8YslDO0NqiPr4NdGa7qcyAhy6etgurc6l3w="

4.4 version：查看构建版本

version 打印二进制构建信息，升级前后各跑一次核对版本：

offen version

实测回显：

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

4.5 debug：打印当前生效配置

debug 解析配置并打印完整 JSON（只读配置、不启动服务），是"改完配置先预检再重启"工作流的核心命令。offen debug -h 全文：


"debug" prints the runtime configuration resolved from the current working
directory.

Usage of "debug":
  -envfile string
    	the env file to use

完整输出与逐字段解读（默认值、LogLevel 数值映射、_FILE 行为）见 《Offen 1.4.2 配置参数详解》第三章，此处给出本机基线配置的字段核对用法：

offen debug 2>&1 | grep -E '"Port"|"Dialect"|"ConnectionString"|"Locale"'

实测回显：

    "Port": 8080,
    "Dialect": "sqlite3",
    "ConnectionString": "/var/opt/offen/offen.db",
    "Locale": "en",

4.6 migrate：应用数据库迁移

migrate 把待应用的数据库迁移跑到配置指向的库上。offen migrate -h 全文：


"migrate" applies all pending database migrations to the connected database.
Only run this command when you run Offen as a horizontally scaling service as
the default installation will handle this routine by itself.

Usage of "migrate":
  -envfile string
    	the env file to use

关键点（-h 原文 + 官方命令文档 Heads Up）：默认单节点模式下迁移在应用启动时自动执行（4.1 启动日志第 3 行即证据），只有横向扩展（OFFEN_APP_SINGLENODE=false）后才需要手动跑。对基线实例手动执行一次验证回显：

offen migrate

实测回显（无待应用迁移时也正常完成）：

time="2026-10-30T01:59:21Z" level=info msg="Successfully ran database migrations"

💡 技术拓展：单节点与多节点两种模式下，"迁移 + 过期清理"这两件例行事务的归属完全不同——

模式数据库迁移过期事件清理
单节点（默认，OFFEN_APP_SINGLENODE=true）应用启动时自动执行进程内置 cron 自动执行
多节点（OFFEN_APP_SINGLENODE=false）升级后手动跑 offen migrate定时任务手动跑 offen expire

本篇实验环境为默认单节点，两个子命令仅作验证性执行；多节点分工是官方命令文档对这两个命令的定位。

4.7 expire：清理过期事件

expire 把超过保留期的历史事件从库中删掉。offen expire -h 全文：


"expire" prunes all events older than 6 months (4464 hours) from the connected
database. Only run this command when you run Offen as a horizontally scaling
service as the default installation will handle this routine by itself.

Usage of "expire":
  -envfile string
    	the env file to use

注意 -h 原文给出口径：6 个月 = 4464 小时（即 186 天，与配置项 OFFEN_APP_RETENTION 默认值一致，可调档位见配置篇 5.5）。这是破坏性操作、不可恢复（官方命令文档原文 "This is a destructive operation and cannot be undone"）。同样仅多节点模式需手动执行，单节点由内置 cron 代跑（4.1 启动日志第 5 行）。对基线实例验证执行：

offen expire

实测回显（基线库内事件均在 6 个月保留期内，删除数为 0）：

time="2026-10-30T01:59:21Z" level=info msg="Successfully expired events" removed=0

4.8 demo：零配置体验实例

demo 起一个一次性实例：自动生成模拟流量数据、使用临时数据库、固定演示账号登录，进程关闭后数据即弃。offen demo -h 全文：


"demo" starts a one-off Offen instance that you can use for testing the software
on your local machine. You can use the username "demo@offen.dev" with password
"demo" to log in. Depending on your setup, generation of random usage data might
take a minute or two.

By default, a random free port will be picked for running the server.
If you need to override this, pass a value to -port.

Usage of "demo":
  -port int
    	the port to bind to (defaults to a random free port)
  -users int
    	the number of users to simulate - this defaults to a random number between 250 and 500 (default -1)

两个参数：-port 指定端口（默认随机空闲端口）、-users 指定模拟访客数（默认在 250–500 间随机）。实测起一个 40 用户的 demo：

offen demo -port 8133 -users 40

实测回显（中间约 2 秒的生成进度条略）：

time="2026-10-30T01:59:38Z" level=info msg="Offen is generating some random usage data for your demo, this might take a little while."
time="2026-10-30T01:59:38Z" level=info msg="You can now start your Offen demo by visiting"
time="2026-10-30T01:59:38Z" level=info
time="2026-10-30T01:59:38Z" level=info msg="--> http://localhost:8133/intro/ <--"
time="2026-10-30T01:59:38Z" level=info
time="2026-10-30T01:59:38Z" level=info msg="in your browser. Please make sure to use the `localhost`"
time="2026-10-30T01:59:38Z" level=info msg="hostname so a secure context is available."

浏览器打开 http://localhost:8133/intro/，用 demo@offen.dev / demo 登录即可看到模拟流量面板（另一组 -users 120 的实测生成了 1313 条事件，面板形态见 《Offen 介绍与选型指南》第五章）。日志里 localhost 提示值得注意：demo 页面依赖浏览器 secure context 存密钥，用 localhost 访问而非机器 IP。

临时库生命周期实测：demo 运行期间在 /tmp 落一个 offen-demo-<uuid>.db：

ls -la /tmp/offen-demo-* | tail -1

实测回显（40 用户的 demo 运行中）：

-rw-r--r-- 1 root root 360448 Oct 30 01:59 /tmp/offen-demo-17494f4d-9967-4eec-8046-75a208b955ab.db

官方说明该文件"进程关闭后删除"；实测从外部 kill 进程后文件仍会残留（见 FAQ Q4），彻底清理用 rm /tmp/offen-demo-*.db。

五、注意事项

  1. 每个子命令都吃 -envfile：不带时走默认查找级联（工作目录优先级最高，易踩坑的优先级实测见配置篇 3.2）；systemd 托管下工作目录为 /，手工前台操作时注意当前目录有没有同名 offen.env。
  2. setup 是一次性命令：只对空库执行成功；重复执行 fatal（4.2 实测），-force 会清数据，执行前先备份 /var/opt/offen/offen.db（或对应数据库快照）。
  3. migrate/expire 与节点模式绑定：单节点不要手动跑（启动与 cron 已覆盖），多节点必须手动补位（分工表见 4.6 拓展）。
  4. expire 不可恢复：删除动作没有 dry-run；多节点把它放进定时任务前，先确认 OFFEN_APP_RETENTION 档位符合业务预期（调短保留期会在启动时立即删数据，见配置篇 FAQ Q3）。
  5. demo 不是精简版生产：它与正式实例同一套面板，但数据在临时库、退出即弃，仅用于体验与演示。
  6. 密码底线 8 位：setup -password 传入不足 8 位直接 fatal（FAQ Q2），交互式输入同样受此校验。

六、常见问题（FAQ）

Q1：offen 报 Error: unknown subcommand "foobar"？ 子命令拼写错误（4.0 首段实测）。用 offen -h 核对七个子命令名：serve、setup、secret、version、debug、migrate、expire；无参运行即 serve。

Q2：setup 报 given password is shorter than 8 characters？ 密码不足 8 位，实测（-password short）：

time="2026-10-30T01:59:21Z" level=info msg="Using command line arguments to create seed account user and account"
time="2026-10-30T01:59:21Z" level=fatal msg="Error bootstrapping database" error="persistence: error validating password for user admin@example.com: keys: given password is shorter than 8 characters"

换足 8 位以上的密码重跑即可（演示账号 q1w2e3r4 即 8 位）。

Q3：对已有数据再次执行 setup 报 action would overwrite existing data？ 这是防误删保护（4.2 实测回显）。确认要清空重建时加 -force；只想加账户/用户请登录面板操作，不走 CLI。

Q4：demo 进程停了，/tmp/offen-demo-*.db 还在？ 官方描述为进程关闭即删除，实测从外部 kill（SIGTERM/SIGKILL）进程后文件会残留（4.8 回显）。残留文件不影响后续 demo（每次新 UUID），确认无需保留数据后 rm /tmp/offen-demo-*.db 清掉即可。

Q5：serve 起不来，报端口相关错误？ 先 offen debug 核对端口配置（见 《Offen 1.4.2 配置参数详解》），再查占用：ss -ltnp | grep :<端口>。AutoTLS 形态要绑定 80/443，还需特权或 CAP_NET_BIND_SERVICE（处理见安装篇 FAQ Q5）。

Q6：单节点实例需要定期跑 migrate/expire 吗？ 不需要。启动日志中的 Successfully applied database migrations 与 Cron successfully pruned expired events 就是内置机制在工作（4.1 回显）；手动再跑无害（4.6/4.7 回显即验证性执行），但没有必要。

七、参考链接