Algernon 1.17.12 配置参数详解

目标：给需要调优、加固或嵌入 Algernon 的运维/开发人员一份完整的参数参考——覆盖 algernon --help 全部 66 个参数拼写（20 个短参数、46 个长参数）的含义、默认值与实测行为，并给出 serverconf.lua 配置入口、参数组合场景与排障沉淀。本文所有「实测」标注的输出均来自 Ubuntu 24.04.5 LTS 服务器上 Algernon 1.17.12 的真实运行回显（已略去终端配色转义符），安装方法见 《Ubuntu 24.04 安装 Algernon 1.17.12 指南》。

一、环境信息

本篇实测环境与工具：

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• 软件：Algernon 1.17.12（官方静态二进制，/usr/local/bin/algernon）
• 依赖组件：Redis 7.x（--redis 验证时本机 redis-server 提供 6379 端口）、OpenSSL 3.x（自签证书）、curl 8.5.0（HTTP 验证）
• 参数全集取证：algernon --help 输出 125 行，本篇逐行核对
• 站点目录：/srv/algernon（含 index.lua / index.md / style.gcss 等演示文件）

版本与帮助输出确认：

algernon --version
algernon --help | wc -l

实测输出：

Algernon 1.17.12
125

二、配置体系总览

Algernon 官方声明「起步不需要任何配置文件」，实际提供三层配置入口，优先级从高到低：

1. 命令行参数：algernon [flags] [要服务的文件或目录] [主机][:端口]，显式传参优先级最高（实测：serverconf.lua 中 SetAddr(":3999") 会被命令行位置参数 :3099 覆盖）；
2. serverconf.lua：用 Lua 函数做服务器级配置，通过 --conf 指定（见第四章）；
3. 内置默认值：监听 :3000、缓存 On、限流 10 请求/秒/客户端、数据库自动回落 BoltDB。

不带任何参数的默认启动横幅（实测，ANSI 转义已略去）：

	Algernon
	1.17.12
	Web Server
-------------------------------------------------
Server directory:	.
Database:		Bolt (/tmp/algernon.db)
Options:		[NonInteractive]
Cache mode:		On
Cache size:		1048576 bytes
Request limit:		10/sec per visitor
Large file threshold:	44040192 bytes
Large file timeout:	10 sec
Listening for:		HTTP  localhost  3000  plain
time="2026-10-23T20:01:35Z" level=info msg="Serving HTTP on http://localhost:3000/"

横幅是参数生效情况的「速查面板」：Database 反映数据库后端选择、Cache mode/size 反映缓存配置、Request limit 反映限流、Options 反映模式开关组合、Listening for 反映协议与端口。改完参数看横幅，是最快的验证方式。

三条默认值必须先记住（后续表格反复引用）：

⚠️ 注意：官方 README 写「默认使用 Redis，无 Redis 时回落 Bolt」，实测无 Redis 时横幅显示 Bolt, temporary（临时内存库），重启丢登录态与缓存元数据；用 --boltdb 或 --bolt 指定文件后才持久化。

三、命令行参数详解

按功能分 10 组覆盖 --help 全部 66 个参数拼写。每组表格给出「参数 | 作用（官方 help 原文意译）| 默认/说明」，实测证据以「✅ 实测」标注。

3.1 监听与基础语法

语法（help 原文）：algernon [flags] [file or directory to serve] [host][:port]，IPv6 地址必须带方括号。

3.2 运行模式开关

模式参数会成组改写多个底层选项，横幅 Options 字段直接显示组合结果：

3.3 协议选择（HTTP/1.1、HTTP/2、HTTP/3）

3.4 数据库后端

默认策略：尝试 Redis :6379 → 失败回落 BoltDB。实测证据齐备：

3.5 缓存控制

3.6 限流与安全头

3.7 TLS 证书与 Let's Encrypt

💡 v1.17.12 Release Notes：证书存储位置已改为 $XDG_DATA_HOME/certmagic、$HOME/.local/share/certmagic 或 /var/lib/algernon；--prod 模式的手工证书约定路径为 /etc/algernon/cert.pem 与 /etc/algernon/key.pem（实测缺证书时 level=error msg="open /etc/algernon/cert.pem: no such file or directory"）。

3.8 事件服务器与自动刷新

3.9 反向代理

--proxy=[/PREFIX=]ENDPOINT：把请求反代到 ENDPOINT（如 3000 或 http://localhost:3000）；带路径前缀（如 /api=）时只代理该前缀，不带则整站代理；可重复多次配置多条规则。

实测（后端为 python3 -m http.server 5000，只绑 IPv4）：

algernon -s --httponly --proxy="/api=http://127.0.0.1:5000" /srv/algernon :3029
curl -s http://localhost:3029/api/index.html

实测输出：

backend-ok

⚠️ 排障实录：--proxy="/api=http://localhost:5000" 时反代 502——Algernon 拨号解析到 [::1]:5000，而后端只监听 IPv4 127.0.0.1。把端点写成 http://127.0.0.1:5000 即恢复 200。双栈环境下反代端点建议显式写 IP 版本。

3.10 日志与杂项

四、serverconf.lua 配置

--conf（旧名 --serverconf）在服务启动阶段执行一个 Lua 文件，适合放不进命令行的结构性配置。实测文件 /tmp/serverconf.lua：

SetAddr(":3999")
OnReady(function()
  log("serverconf.lua loaded, ServerInfo:")
  log(ServerInfo())
end)

启动与实测回显：

algernon -s --conf=/tmp/serverconf.lua --nodb /srv/algernon :3099

level=info msg="serverconf.lua loaded, ServerInfo:"
level=info msg="TLS certificate: cert.pem / TLS key: key.pem
Cache mode: on
Database: no database backend
Compression: on
Server: {}
Options: {}
Serving /srv/algernon
HTTP/2 (no port specified)
"

两个实测结论：

1. 命令行位置参数覆盖 SetAddr：serverconf.lua 里的 SetAddr(":3999") 被命令行的 :3099 覆盖——结构性配置放 serverconf，运行时端口用命令行，二者不要同时表达同一件事；
2. ServerInfo() 是排查配置加载结果的利器，把缓存模式、数据库、压缩、监听情况一次性打印出来。

常用的 serverconf 函数族（完整清单用 REPL 的 webhelp/confighelp 自省，见 D1 篇）：SetAddr、SetPorts、SetDir、SetCacheMode、SetLimit、SetTheme、SetSaveLog、SetHideDotfiles、AddReverseProxy、AddUserPrefix、SetUserPrefix、OnReady、ServerInfo。

.alg/.zip 应用包内的 serverconf.lua 随包加载，无需 --conf 显式指定。

五、参数组合实战

5.1 开发热重载（help 官方推荐组合）

algernon --dev --httponly --debug --autorefresh --bolt --noninteractive . :4000

Debug 显示错误 + /sse 自动刷新 + Bolt 固定文件 + 固定端口。改 index.lua 保存后浏览器自动刷新。

5.2 多域名 HTTP/2 生产（help 官方推荐组合）

algernon -c --domain --noninteractive --cachesize 67108864 --prod /srv

/srv/mydomain.com、/srv/otherweb.com 各自映射域名，statcache + 64MB 缓存 + prod 模式，80/443 双端口。

5.3 QUIC 实验（help 官方推荐组合）

algernon -s -u -n . :7000

需补 --cert/--key，否则 QUIC 自动回落（见 3.3 实测）。

5.4 systemd 托管最小组合（B1 篇主方案）

ExecStart=/usr/local/bin/algernon --httponly --addr=:3000 --noninteractive --boltdb=/var/lib/algernon/algernon.db /srv/algernon

5.5 纯静态无状态速起

algernon -x

当前目录、常规 HTTP、无数据库、无限流、无缓存依赖——help 把它作为最简示例收录。

六、排障实录

6.1 -x 模式悄悄关掉限流与数据库

现象：algernon -x --limit=2 后连打 8 个请求全部 200，未出现 429。

定位：横幅显示 Request limit: Off、Database: Disabled。回读 help 原文：-x, --simple 的定义是 "disable all features that requires a database"——限流状态存储依赖数据库，所以一并被关。

处理：要限流就不能用 -x，改用 -s --httponly --boltdb=...。-x 只适合「纯静态、无状态」的临时分发场景。

6.2 目录列表链接带出莫名前缀

现象：curl http://localhost:3000/sub/ 的目录列表里，文件链接渲染为 <a href="/b/a.txt">a.txt</a>，多出一个 /b/ 前缀。

定位：v1.17.12 Release Notes 新增 --dirbaseurl flag「for placing a base URL in front of the links in the directory listing」，目录列表的链接前缀不再默认等于请求路径。

处理：启动参数显式加 --dirbaseurl=/，实测链接恢复 <a href="/one.txt">one.txt</a>。需要把 Algernon 放在反向代理子路径后时，则把 --dirbaseurl 设为该子路径。

6.3 Server 响应头在 -x 模式下消失

现象：--servername=MyEdge/1.0 在常规模式下生效（curl -D- 可见），-x 模式下响应头完全没有 Server 字段。

定位：-x 精简模式同时精简了响应头集合，与 6.1 同源——-x 关闭的不只是数据库，还包括一批「非必要」输出。

处理：对外暴露自定义 Server 头时避开 -x。

6.4 --prod 无证书时的报错路径

现象：algernon --prod 报 level=error msg="open /etc/algernon/cert.pem: no such file or directory"。

定位：--prod 固定按 /etc/algernon/cert.pem、/etc/algernon/key.pem 找证书，且强制监听 80/443（非 root 需要 setcap）。

处理：手工证书放 /etc/algernon/ 下或用 --cert/--key 显式指定；自动化签发改用 --letsencrypt --domain。

七、常见问题 FAQ

Q1：--cachesize 与横幅 Cache size 数值对不上？ 默认横幅 1048576（1MB）；help 的 Example 中给出 --cachesize 67108864 的用法，显式传参后横幅同步为准。判断当前值一律看横幅。

Q2：--limit 传了却不生效？ 检查是否同时用了 -x（见 6.1）；-x 会关限流。去掉 -x 并给一个真实数据库后端（Bolt 文件即可）。

Q3：-n 不打印横幅？ 1.17.12 实测 -n 仍打印横幅（与 help 文案不符），要静默用 -q，但 -q 连访问日志之外的报错也会吞掉，排障期别用。

Q4：IPv6 怎么监听？ --addr='[::1]:3000' 或 [2001:db8::1]:443，方括号必须有。

Q5：限流 429 的响应头有哪些？ X-Rate-Limit-Limit（阈值）、X-Rate-Limit-Duration（1s）、X-Rate-Limit-Request-Forwarded-For（客户端标识），实测与 tollbooth 库行为一致。

Q6：怎么确认我的参数组合最终生效了什么？ 启动横幅六行速查（Database/Cache/Request limit/Options/Listening）+ ServerInfo()（serverconf.lua 中打印），两条路覆盖全部关键配置。

八、参考链接

1. 官方 README（配置与函数清单）：https://github.com/xyproto/algernon
2. TUTORIAL（serverconf 与 Lua 函数教程）：https://github.com/xyproto/algernon/blob/main/TUTORIAL.md
3. v1.17.12 Release Notes（新参数与行为变更）：https://github.com/xyproto/algernon/releases/tag/v1.17.12
4. 本专栏姊妹篇：《Algernon 1.17.12 介绍与选型指南》、《Ubuntu 24.04 安装 Algernon 1.17.12 指南》