remark42 1.18.0 配置参数详解

目标：系统梳理 remark42 v1.18.0 的全部服务端配置参数（环境变量），按「存储/缓存/认证/管理员/通知/SMTP/头像/图片/投票/行为限制/SSL/前端」分类逐项给出真实默认值、取值说明与实测验证方式。全部参数清单取自 v1.18.0 二进制 server --help 实际输出（864 行），核心参数改动后均已重启服务并用 /api/v1/config 回读或行为实测验证生效（实测于 2026-10-22，Ubuntu 22.04.5 + remark42 v1.18.0）。

一、环境信息

本章列出参数验证环境与信息来源基准。

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），服务以 systemd 托管（安装方式见《Ubuntu 22.04 安装 remark42 指南》篇第四章）；
• remark42 版本：v1.18.0（自报版本 remark42 v1.18.0-13b2035c-20261011T191723）；
• 实测时间：2026-10-22；
• 配置载体：/opt/remark42/remark42.env（systemd EnvironmentFile 注入），改动后 systemctl restart remark42 生效；
• 参数清单来源：remark42.linux-amd64 server --help 实际输出（全部命令行参数及其 [$环境变量] 注入名与默认值）；参数名与 --help 中方括号内的环境变量一一对应，如 --store.type=... [$STORE_TYPE]；
• 生效验证来源：GET /api/v1/config?site=mysite 回读 JSON（服务端运行时真实生效值）与行为实测（JWT 有效期、超长评论拒绝等）。

二、前置条件

本章说明阅读与实操本篇前需要具备的条件。

1. 已按《Ubuntu 22.04 安装 remark42 指南》篇完成安装并可访问 /api/v1/ping（返回 pong）；
2. 知道自己的环境变量文件位置（本文以 /opt/remark42/remark42.env 为例）；
3. 修改参数的基本动作（每处改动都遵循同一模式，不再重复）：

# 追加或修改参数
echo 'MAX_COMMENT_SIZE=8192' >> /opt/remark42/remark42.env
# 重启生效并确认状态
systemctl restart remark42 && systemctl is-active remark42

实测回显：

active

4. 回读验证命令（本文所有「实测验证」的统一口径）：

curl -s "http://127.0.0.1:8131/api/v1/config?site=mysite" | python3 -m json.tool

实测回显（本文实验环境最终状态，见第五章各参数的改动记录）：

{
    "version": "v1.18.0-13b2035c-20261011T191723",
    "edit_duration": 600,
    "admin_edit": false,
    "min_comment_size": 2,
    "max_comment_size": 4096,
    "admins": [
        "auth_anon_admin01"
    ],
    "admin_email": "admin@example.org",
    "auth_providers": [
        "anonymous"
    ],
    "anon_vote": true,
    "low_score": -3,
    "critical_score": -8,
    "positive_score": true,
    "readonly_age": 7,
    "max_image_size": 2097152,
    "email_notifications": false,
    "telegram_notifications": false,
    "emoji_enabled": true,
    "simple_view": true,
    "send_jwt_header": false,
    "subscribers_only": false
}

💡 说明：/api/v1/config 回读是「配置是否真正生效」的最权威依据——它返回的是服务进程内存中的运行时值，而不是环境变量文件里写了什么。排查「改了没生效」问题时始终以该接口为准。

三、参数查看与修改方式

remark42 没有配置文件格式，一切配置皆环境变量（或等价的命令行参数）。本章说明三种查看途径与一种修改途径。

途径一：server --help 查看全部参数与默认值（离线、最权威）：

/opt/remark42/bin/remark42.linux-amd64 server --help | grep -cE '\[\$'

实测回显（环境变量注入点总数）：

159

每个参数的 --help 输出片段形如：

      --store.type=[bolt|rpc]   type of storage (default: bolt) [$STORE_TYPE]

含义：命令行参数 --store.type、可选值 bolt|rpc、默认值 bolt、等价环境变量 STORE_TYPE。

途径二：/api/v1/config 回读运行时核心值（在线、验证生效），见第二章第 4 条。

途径三：systemctl show remark42 --property=EnvironmentFiles 确认配置来源：

systemctl show remark42 --property=EnvironmentFiles

实测回显：

EnvironmentFiles=/opt/remark42/remark42.env (ignore_errors=no)

修改方式：直接编辑环境变量文件后重启服务（见第二章第 3 条）。remark42 不支持热加载，必须 systemctl restart remark42。

四、参数总览

v1.18.0 服务端参数共分 12 组（依据 server --help 的分组结构），总览如下：

参数命名规律说明：官方文档站旧版使用 REMARK42_ 前缀（如 REMARK42_SECRET），当前版本二进制的环境变量注入名为裸名（SECRET、REMARK_URL、STORE_TYPE…），以 --help 输出中方括号里的名字为准。两套写法在网上资料中混用，遇到「配了没生效」先核对注入名（见第九章 Q1）。

五、核心参数分类详解

本章按参数组分节，给出逐项说明。每节末尾标注本文实测过的参数与验证结果。

5.1 应用级参数：REMARK_URL / SECRET / DEBUG

服务身份三件套，缺一不可（SECRET 缺失或 REMARK_URL 缺失时服务启动即失败）。

本文实测配置（env 文件节选）与验证：

REMARK_URL=http://10.89.57.2:8131
SECRET=530108254a0b822ff52e24557efde094ec2ff140d25b80d3

systemctl restart remark42 && curl -s http://127.0.0.1:8131/api/v1/ping

pong

REMARK_URL 正确性会直接体现在匿名登录返回的头像地址中（与配置值前缀一致，实测 picture 字段为 http://10.89.57.2:8131/api/v1/avatar/...）。

5.2 服务监听与站点参数（server 组）

本文实测验证（追加到 env 后重启，/api/v1/config 回读比对）：

MAX_COMMENT_SIZE=4096
MIN_COMMENT_SIZE=2
EDIT_TIME=10m
READONLY_AGE=7
LOW_SCORE=-3
CRITICAL_SCORE=-8
POSITIVE_SCORE=true
EMOJI=true
SIMPLE_VIEW=true

实测回显（节选，改动项全部生效）：

{
    "edit_duration": 600,
    "min_comment_size": 2,
    "max_comment_size": 4096,
    "low_score": -3,
    "critical_score": -8,
    "positive_score": true,
    "readonly_age": 7,
    "emoji_enabled": true,
    "simple_view": true
}

行为级验证两条：

# 1) 超长评论拒绝（MAX_COMMENT_SIZE=4096 时发送 4200 字符）
{"code":4,"details":"invalid comment","error":"comment text exceeded max allowed size 4096 (4200)"}
# 2) EDIT_TIME=10m 使 edit_duration 从默认 300 变为 600（回读值，单位秒）

5.3 存储参数（store 组）

💡 技术拓展：评论存储引擎的两种路线——

类型	原理	适用场景
bolt（内嵌 KV）	bbolt 单文件 B+ 树，进程内读写，零外部依赖	单实例部署，绝大多数站点
rpc（远程存储）	评论读写转发到独立扩展服务	多实例共享数据、存储需独立扩容

本文/本方案实际采用 bolt：单二进制自包含是 remark42 的核心卖点，单实例场景无理由引入外部存储。

本文实测配置：

STORE_TYPE=bolt
STORE_BOLT_PATH=/opt/remark42/var

落盘验证（重启并发表评论后，数据文件生成于配置目录）：

ls -la /opt/remark42/var/

实测回显（mysite.db 即站点 mysite 的 bolt 数据库，avatars/pictures 随首次使用自动创建）：

total 88
drwxr-xr-x 4 remark42 remark42   4096 Oct 22 02:00 .
drwxr-xr-x 5 remark42 remark42   4096 Oct 22 01:59 ..
drwx------ 5 remark42 remark42   4096 Oct 22 02:29 avatars
-rw------- 1 remark42 remark42 131072 Oct 22 02:29 mysite.db
drwx------ 2 remark42 remark42   4096 Oct 22 02:00 pictures

5.4 缓存参数（cache 组）

实测说明：单实例使用默认 mem 即可；本文实验环境未改缓存参数，默认值均按 --help 实际输出记录。

5.5 认证参数（auth 组）

remark42 登录体系的开关与凭据都在本组。配置哪种登录方式，评论区登录面板就出现哪种入口（/api/v1/config 回读的 auth_providers 数组是运行时真实清单）。

本文实测配置与验证：

AUTH_ANON=true

实测回显（config 回读 auth_providers 只含已启用方式）：

"auth_providers": ["anonymous"]

行为级实测（匿名登录返回用户身份；JWT TTL 改 15m 后实际令牌 900 秒）：

AUTH_TTL_JWT=15m
curl -s "http://127.0.0.1:8131/auth/anonymous/login?user=ttlcheck&aud=mysite" >/dev/null
# 解析返回 JWT 的 payload：exp - iat = 900

jwt ttl seconds: 900

⚠️ 注意：GitHub 等社交登录的回调地址固定为 <REMARK_URL>/auth/<provider>/callback。OAuth 应用里登记的回调地址必须与 REMARK_URL 完全一致（含协议与端口），否则登录跳转 404 或回调校验失败。匿名与邮箱登录用户的昵称不可冒充管理员名（服务端强制拦截，属内置保护）。

5.6 管理员参数（admin 组）

本文实测配置：

ADMIN_SHARED_ID=auth_anon_admin01
ADMIN_SHARED_EMAIL=admin@example.org
ADMIN_PASSWD=q1w2e3r4

实测验证（config 回读 admins 与 admin_email 同步变化）：

"admins": ["auth_anon_admin01"],
"admin_email": "admin@example.org",

管理接口 Basic Auth 实测（用户名固定 admin，密码即 ADMIN_PASSWD）：

curl -s -u "admin:q1w2e3r4" "http://127.0.0.1:8131/api/v1/admin/user/anonymous_514e6574a9504050ad8895e9f7da2f9f4eb3f4b6?site=mysite"

{"name":"testreader01","id":"anonymous_514e6574a9504050ad8895e9f7da2f9f4eb3f4b6","picture":"...","ip":"306455241a46620d8ca3b24b804c1a2f29c64419","admin":false,"site_id":"mysite"}

5.7 通知参数（notify 组）

通知分「用户通知」（回复提醒）与「管理员通知」（每条新评论）两条管道，v1.18.0 起 NOTIFY_TYPE 已标注 deprecated，按管道分别配置。

实测说明：通知管道依赖 SMTP（email）或外部 IM 凭据（telegram/slack），本文实验环境保持默认关闭（config 回读 email_notifications:false、telegram_notifications:false），各参数默认值均按 --help 实际输出记录。

5.8 SMTP 参数（smtp 组）

邮箱登录与邮件通知共用的发信通道。SMTP 未配置时，AUTH_EMAIL_ENABLE 与 NOTIFY_USERS=email/NOTIFY_ADMINS=email 均无法工作。

配置示例（以 587 端口 StartTLS 服务商为例，凭据按实际填）：

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=no-reply@example.com
SMTP_PASSWORD=YourSmtpPass
SMTP_STARTTLS=true
AUTH_EMAIL_ENABLE=true
AUTH_EMAIL_FROM=no-reply@example.com

5.9 头像参数（avatar 组）

本文实测配置 AVATAR_RESIZE=64（配合评论页头像小尺寸展示，降低磁盘占用）；匿名用户头像由服务端按用户 ID 生成（登录返回的 picture 字段指向 /api/v1/avatar/<哈希>.image）。

5.10 图片参数（image 组）

本文实测配置 IMAGE_MAX_SIZE=2097152（2MB，实测回读 max_image_size:2097152 生效）。

5.11 投票参数与行为限制（server 组内）

投票与垃圾治理相关参数（默认值实测取自 --help 输出）：ANON_VOTE（false，匿名投票，需与 VOTES_IP 同开）、VOTES_IP（false，同 IP 去重）、VOTES_IP_TIME（5m）、MAX_VOTES（-1 不限）、LOW_SCORE（-5 折叠）、CRITICAL_SCORE（-10 隐藏）、POSITIVE_SCORE（false 仅正分）。

本文实测配置：

ANON_VOTE=true
VOTES_IP=true
VOTES_IP_TIME=10m
MAX_VOTES=5

实测验证：config 回读 anon_vote:true；匿名用户对他人评论投票成功（{"id":"cabcece9-...","score":1}），自投被拒（can not vote for his own comment，见安装篇 Q3）。

5.12 SSL 与图片代理参数（ssl / image-proxy 组）

💡 说明：生产建议把 remark42 置于 Nginx/Caddy 反代之后终结 TLS（SSL_TYPE=none），仅当无反代时才启用内建 SSL。IMAGE_PROXY_* 两项开启后可避免评论区出现混合内容告警，也阻止第三方图片站通过评论图片收集读者 IP。

六、生产配置模板

给出两档可直接落地的生产模板（写入 /opt/remark42/remark42.env 后 systemctl restart remark42 生效）。

6.1 个人博客模板（1C1G 服务器，日均 PV < 1 万）

REMARK_URL=https://remark.example.org
SECRET=<openssl rand -hex 24 生成>
SITE=blog
STORE_TYPE=bolt
STORE_BOLT_PATH=/opt/remark42/var
BACKUP_PATH=/opt/remark42/backup
REMARK_PORT=8131
MAX_COMMENT_SIZE=4096
READONLY_AGE=180
AUTH_GITHUB_CID=<GitHub OAuth App Client ID>
AUTH_GITHUB_CSEC=<GitHub OAuth App Client Secret>
ADMIN_SHARED_ID=github_<你的GitHub数字ID>
ADMIN_SHARED_EMAIL=admin@example.org
ADMIN_PASSWD=<强口令>
EMOJI=true

适用场景说明：单一博客站点、GitHub 登录为主、180 天后旧文自动关评、bolt 单文件存储（磁盘占用与评论量线性相关，10 万条评论量级仍在百 MB 内）。

6.2 多站点/技术社区模板（2C4G，多个子站共用评论）

REMARK_URL=https://remark.example.org
SECRET=<openssl rand -hex 24 生成>
SITE=blog,docs,news
STORE_TYPE=bolt
STORE_BOLT_PATH=/opt/remark42/var
CACHE_TYPE=mem
CACHE_MAX_ITEMS=5000
REMARK_PORT=8131
MAX_COMMENT_SIZE=8192
AUTH_ANON=true
RESTRICTED_NAMES=admin,administrator,root
LOW_SCORE=-3
CRITICAL_SCORE=-6
NOTIFY_ADMINS=webhook
NOTIFY_WEBHOOK_URL=https://hook.example.com/xxx
ALLOWED_HOSTS=blog.example.org,docs.example.org,news.example.org
ADMIN_SHARED_ID=github_<你的GitHub数字ID>
ADMIN_PASSWD=<强口令>

适用场景说明：三站点共用实例（SITE 逗号分隔），开启匿名但用禁用名与低分阈值治理垃圾，管理端新评论走 webhook 接入自有告警；ALLOWED_HOSTS 限制组件只可被自有域嵌入。

七、常见问题（FAQ）

Q1：参数改了却没生效？

先核对三件事：① 环境变量注入名是否为裸名（SECRET）而非旧文档的 REMARK42_ 前缀（REMARK42_SECRET）——以 server --help 方括号内的名字为准；② 是否重启了服务（remark42 不支持热加载）；③ 以 GET /api/v1/config?site=<站点> 回读为准判断是否生效，而不是看文件内容。

Q2：SECRET 可以换吗？换了会怎样？

可以换，但换后全部已登录用户的 JWT 立即失效（旧令牌验签不过），读者需重新登录；评论数据不受影响。安全事件（SECRET 疑似泄露）时应立即轮换。

Q3：SITE 想加一个站点，历史评论会受影响吗？

不会。评论按 site_id + 页面 URL 双键归档，新增站点 ID 只是多出一个命名空间；SITE 是逗号分隔白名单，去掉某个站点后其历史评论仍在库里但不接受新写入。

Q4：把 MAX_COMMENT_SIZE 调得很大有风险吗？

有。评论正文存储、渲染与传输成本随长度线性增长，且超长文本是低成本灌水载体；配合 RESTRICTED_WORDS 与 LOW_SCORE 治理比单纯放大上限更有效。实测 4200 字符文本在 4096 上限下被明确拒绝（comment text exceeded max allowed size 4096 (4200)），拒绝行为本身不消耗存储。

Q5：SMTP 配错了会发生什么？

服务照常运行（SMTP 是惰性依赖），但邮箱登录不可用、邮件通知静默丢弃；判断方法：config 回读中 email_notifications 恒为 false、评论区登录面板不出现邮箱入口。建议接入前先用 NOTIFY_ADMINS=email 发一条测试评论验证收信链路。

Q6：多实例部署要改哪些参数？

至少三处：STORE_TYPE=rpc 指向共享存储扩展（bolt 是单文件库，多实例直连同一文件会损坏数据）；CACHE_TYPE=redis_pub_sub 保证跨实例缓存失效；负载均衡层保持会话无关（JWT 无状态，无需粘滞会话）。

八、参考链接

• 官方配置变量文档：https://remark42.com/docs/configuration/variables/
• 官方安装文档：https://remark42.com/docs/getting-started/installation/
• v1.18.0 源码参数定义（backend/app/cmd/server.go）：https://github.com/umputun/remark42/blob/v1.18.0/backend/app/cmd/server.go
• 本专栏配套：《remark42 1.18.0 介绍与选型指南》（架构与选型）、《Ubuntu 22.04 安装 remark42 指南》（安装与 systemd 托管）、《remark42 运维命令与 API 实操详解》（子命令与管理 API）