Memos 0.31.0 配置参数详解

目标：系统讲清 Memos 0.31.0 的全部配置面——13 个启动参数（CLI flags 与 MEMOS_* 环境变量双通道）、/etc/secrets 部署配置文件层，以及 7 组存数据库的实例设置（GENERAL/STORAGE/MEMO_RELATED/TAGS/NOTIFICATION/AI/ACCESS），每一项均给出真实默认值、取值校验规则与实测回显，并给出两套生产配置模板。文中全部命令与回显均在真实服务器环境（Ubuntu 24.04.5 LTS、Memos 0.31.0 官方二进制 + systemd 托管，监听 8081，数据目录 /var/opt/memos）实测通过。

一、环境信息

本篇实测环境的关键信息如下：

操作系统：Ubuntu 24.04.5 LTS（PRETTY_NAME 实查）
Memos：0.31.0（官方单二进制，静态链接，GitHub Releases 资产 memos_0.31.0_linux_amd64.tar.gz，2026-09-20 发布）
安装位置：二进制 /usr/local/bin/memos，数据目录 /var/opt/memos
进程托管：systemd 服务 memos.service（systemctl is-active 实测 active）
监听端口：8081（0.31.0 二进制默认端口，--port 默认值实查）
数据库：sqlite（默认驱动，库文件 /var/opt/memos/memos_prod.db，实测 schema 版本 0.31.8）
管理账号：root / q1w2e3r4（实例管理员 Host）
组件背景：Memos 的定位与选型见《Memos 介绍与选型指南》；Compose 编排部署形态（端口 5230 的由来）见本专栏《Memos 0.31.0 Docker Compose 部署指南》；本篇所有参数命令在《Memos 0.31.0 常用 CLI 命令与工具详解》亦有逐条命令行实测

二、前置条件

本篇假设服务器上已有一个可用的 Memos 0.31.0 实例。若从零开始，按以下三步完成基线安装（全部命令在本篇实测环境逐条执行过）。

1. 下载并安装官方二进制（先下载校验文件核对，再解压安装）：

cd /opt/memos
wget https://github.com/usememos/memos/releases/download/v0.31.0/memos_0.31.0_linux_amd64.tar.gz
wget https://github.com/usememos/memos/releases/download/v0.31.0/checksums.txt
sha256sum -c checksums.txt 2>/dev/null | grep linux_amd64

第三条命令实测回显（校验通过）：

memos_0.31.0_linux_amd64.tar.gz: OK

⚠️ 注意：GitHub Releases 下载属于境外资源，国内服务器下载慢或失败时走代理：wget -x http://192.168.1.62:7897 <URL>（按自己网络环境替换代理地址）。

tar -xzf memos_0.31.0_linux_amd64.tar.gz
mv memos /usr/local/bin/memos
chmod +x /usr/local/bin/memos
memos version

实测回显：

0.31.0

2. 准备数据目录（Memos 在该目录存在且可写时自动将其作为默认数据目录）：

mkdir -p /var/opt/memos

3. 建 systemd 服务并启动，/etc/systemd/system/memos.service 内容：

[Unit]
Description=Memos self-hosted memo service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/var/opt/memos
ExecStart=/usr/local/bin/memos --data /var/opt/memos --port 8081
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

systemctl daemon-reload
systemctl enable memos
systemctl start memos
systemctl is-active memos

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/memos.service → /etc/systemd/system/memos.service.
active

浏览器访问 http://<服务器IP>:8081 注册首个管理员账号（本文用 root/q1w2e3r4），或直接调注册接口 POST /api/v1/users。

三、参数查看与修改方式

Memos 0.31.0 的配置共有四个入口，修改前先弄清每个入口「管什么、谁优先」：

入口	形态	管什么	生效方式
CLI 启动参数	`memos --port 8081`	部署级事项（监听/数据/驱动）	重启进程
环境变量	`MEMOS_PORT=5230`	同上，与启动参数同名等价	重启进程
`/etc/secrets` 文件	JSON 文件（0.31 新增）	敏感部署配置（SSO/SMTP/AI Key）与实例设置覆盖	重启进程
实例设置（Web/API）	存数据库 `system_setting` 表	站点品牌、注册策略、附件存储、AI 等 7 组	保存即生效

优先级（实测验证）：显式传入的 CLI 参数 > 环境变量 > 内置默认值。实测：0.31.0 默认端口 8081，不改任何配置时启动日志为 Server running on port 8081；设置环境变量后：

MEMOS_PORT=5231 memos --data /var/opt/memos

实测启动日志（环境变量生效）：

Memos 0.31.0 started successfully!
Data directory: /var/opt/memos
Database driver: sqlite
Server running on port 5231
Access your memos at: http://localhost:5231
Access mode: private

而同时给 MEMOS_PORT=5231 与命令行 --port 5232 时，命令行显式值胜出（viper 绑定规则：显式修改的 flag > env > 默认值）。生产建议二选一并固定：systemd 托管用 ExecStart 参数或 Environment= 均可，Compose 编排用环境变量。

参数的权威清单随时可用帮助命令自检（以本机二进制实际输出为准）：

memos --help

实测回显（完整）：

Usage:
  memos [flags]
  memos [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  version     Print the current Memos version

Flags:
      --addr string                                 address of server
      --data string                                 data directory
      --demo                                        enable demo mode
      --driver string                               database driver (sqlite, mysql, postgres, d1) (default "sqlite")
      --dsn string                                  database source name (DSN)
  -h, --help                                        help for memos
      --instance-url string                         canonical external URL of the Memos instance
      --log-level string                            log verbosity level (debug, info, warn, error) (default "info")
      --port int                                    port of server (default 8081)
      --rate-limit                                  enable request rate limiting (default true)
      --trusted-proxies strings                     proxies whose forwarding headers identify the client: CIDRs, IPs, "private" (default; the loopback and private ranges), or "none" when the instance is reached without a header-rewriting proxy (default [private])
      --unix-sock string                            path to the unix socket, overrides --addr and --port
  -V, --version                                     print the current Memos version
      --webhook-private-network-allowlist strings   private webhook destinations to allow (exact hostname, IP, or CIDR)

Use "memos [command] --help" for more information about a command.

实例设置层的查看与修改走 HTTP API（Web 设置页与之一一对应）。以管理员身份登录获取访问令牌，然后读写设置（读一般无需管理员，写需要）：

TOKEN=$(curl -s -X POST http://127.0.0.1:8081/api/v1/auth/signin -H "Content-Type: application/json" -d '{"passwordCredentials":{"username":"root","password":"q1w2e3r4"}}' | python3 -c "import json,sys; print(json.load(sys.stdin)['accessToken'])")
curl -s http://127.0.0.1:8081/api/v1/instance/settings/GENERAL -H "Authorization: Bearer $TOKEN"

实测回显（全新实例的 GENERAL 默认值）：

{"name":"instance/settings/GENERAL","generalSetting":{"disallowUserRegistration":false,"disallowPasswordAuth":false,"additionalScript":"","additionalStyle":"","weekStartDayOffset":0,"disallowChangeUsername":false,"disallowChangeNickname":false}}

改用 PATCH /api/v1/instance/settings/<KEY> 保存，保存即生效、无需重启。也可在数据库层直接观察设置的落库情况（system_setting 表只存「改过的」设置项，未改过的项不落库）：

sqlite3 /var/opt/memos/memos_prod.db "SELECT name, value FROM system_setting;"

实测回显（本机改过 GENERAL 与 ACCESS 后）：

BASIC|{"secretKey":"6ae77422-9f93-4a35-8e67-ec118b9a9c1a","schemaVersion":"0.31.8"}
ACCESS|{"accessMode":"INSTANCE_ACCESS_MODE_PRIVATE"}
GENERAL|{"customProfile":{"title":"quzuo 实验室","description":"自托管闪念笔记"}}

💡 说明：BASIC 行由系统自写（实例加密用的 secretKey 与 schema 版本），不要手工改。数据库是 SQLite 时可用 sqlite3 只读查询（sqlite3 "file:/var/opt/memos/memos_prod.db?mode=ro"），写操作一律走 API/Web，避免与运行中进程争锁。

四、参数总览

启动参数总表（env 名 = MEMOS_ 前缀 + 参数名中划线转下划线；默认值为 0.31.0 --help 与源码实查）：

启动参数	环境变量	默认值	作用
`--port`	`MEMOS_PORT`	8081（官方 Compose 方案预置 5230）	HTTP 监听端口
`--addr`	`MEMOS_ADDR`	空（全网卡）	监听地址
`--unix-sock`	`MEMOS_UNIX_SOCK`	空	Unix socket 监听，设置后覆盖 addr/port
`--data`	`MEMOS_DATA`	`/var/opt/memos`（存在且可写时）	数据目录
`--driver`	`MEMOS_DRIVER`	sqlite	数据库驱动 sqlite/mysql/postgres/d1
`--dsn`	`MEMOS_DSN`	空	数据库连接串
`--instance-url`	`MEMOS_INSTANCE_URL`	空	实例对外规范 URL（http/https）
`--demo`	`MEMOS_DEMO`	false	演示模式（仅 sqlite）
`--log-level`	`MEMOS_LOG_LEVEL`	info	日志级别 debug/info/warn/error
`--rate-limit`	`MEMOS_RATE_LIMIT`	true	请求限流开关
`--trusted-proxies`	`MEMOS_TRUSTED_PROXIES`	private	可信代理网段
`--webhook-private-network-allowlist`	`MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST`	空	webhook 内网目标白名单
`--allow-private-webhooks`	`MEMOS_ALLOW_PRIVATE_WEBHOOKS`	false	已废弃，被白名单参数取代

另有子命令 version（打印版本）、completion（shell 补全脚本）、help；-V/--version 与 version 子命令输出一致（均为 0.31.0）。

实例设置 7 组总表（存数据库，API 键 = instance/settings/<KEY>）：

设置键	管什么	典型修改场景
GENERAL	站点品牌、注册/改昵称策略、自定义脚本样式	关闭注册、改站点标题
STORAGE	附件存储类型与多存储后端（DATABASE/LOCAL/S3）	接入 S3/R2、改上传上限
MEMO_RELATED	单条 memo 长度上限、双击编辑、表情反应集	调大单条上限
TAGS	标签元数据（背景色、内容模糊）	敏感标签自动模糊
NOTIFICATION	SMTP 邮件通知通道	配置发信邮箱
AI	AI 提供商（OPENAI/GEMINI）与语音转写	接入转写模型
ACCESS	实例访问模式（私有/公开）	公开分享型实例

五、服务监听与网络类参数

5.1 `--port` / `MEMOS_PORT`

监听端口，整数，默认 8081。两个常踩的版本事实：官方 Compose 方案把 MEMOS_PORT 预置为 5230，因此编排部署的默认端口是 5230；二进制裸跑（本章环境）是 8081。改法二选一：

# 方式一：systemd ExecStart 里写参数
ExecStart=/usr/local/bin/memos --data /var/opt/memos --port 8090
# 方式二：systemd 用 Environment 注入（每行一个 Environment=）
Environment=MEMOS_PORT=8090

改完 systemctl daemon-reload && systemctl restart memos，验证：

ss -ltn | grep 8090

实测回显（改到 8090 后）：

LISTEN 0 4096 [::]:8090 [::]:* users:(("memos",pid=405,fd=7))

5.2 `--addr` / `MEMOS_ADDR`

监听地址，默认空（等价全网卡 0.0.0.0）。只对内网提供服务时绑定回环地址：

memos --addr 127.0.0.1 --port 8081

实测启动日志（地址生效后访问提示随之变化）：

Memos 0.31.0 started successfully!
Data directory: /var/opt/memos
Database driver: sqlite
Server running on 127.0.0.1:8081
Access your memos at: http://127.0.0.1:8081
Access mode: private

配置反向代理（Nginx/Caddy）对外、Memos 只听本机时，这是标准的收口组合：--addr 127.0.0.1 + 反代转发 + --trusted-proxies 声明代理网段（5.4 节）。

5.3 `--unix-sock` / `MEMOS_UNIX_SOCK`

改为监听 Unix socket，设置后覆盖 --addr/--port。适合同机反代（Nginx proxy_pass http://unix:/path）或本机工具直连：

memos --data /var/opt/memos --unix-sock /var/opt/memos/memos.sock

实测启动日志：

Memos 0.31.0 started successfully!
Data directory: /var/opt/memos
Database driver: sqlite
Server running on unix socket: /var/opt/memos/memos.sock
Access mode: private

socket 通道可用 curl 实测（等效 HTTP 请求）：

curl -s --unix-socket /var/opt/memos/memos.sock http://localhost/api/v1/instance/profile

实测回显：

{"version":"0.31.0","demo":false,"instanceUrl":"","commit":"2b2192d4e153bd04f1d325b60fd880cf00d68b01","needsSetup":true,"accessMode":"INSTANCE_ACCESS_MODE_PRIVATE"}

5.4 `--instance-url` / `MEMOS_INSTANCE_URL`

实例对外规范 URL，用于分享链接、webhook 回调等需要绝对地址的场景；只允许 http/https。非法值会在启动期直接拒绝（fail-fast 校验，实测）：

memos --instance-url "ftp://x"

实测报错（进程退出码 1，不启动）：

time=2026-10-22T08:54:49.955+08:00 level=ERROR msg="memos failed" error="failed to validate profile: instance URL must use http or https, got \"ftp\""

正确形态带协议与端口（非 80/443 时）：

memos --instance-url "http://192.168.146.128:8081" --data /var/opt/memos

💡 说明：0.31 起「实例访问模式（公开/私有）」改为存数据库（ACCESS 设置，第八章），与 --instance-url 解耦——改公开/私有不再动启动参数。

5.5 `--trusted-proxies` / `MEMOS_TRUSTED_PROXIES`

声明「哪些代理的转发头（X-Forwarded-For 等）可信」，用于还原客户端真实 IP。取值为 CIDR 列表或三个关键字之一，默认 private（即全部回环与私网段视为可信代理）；只在流量经反代进入时需要配置。取值语义（--help 原文）：CIDRs, IPs, "private" (default; the loopback and private ranges), or "none" when the instance is reached without a header-rewriting proxy。典型用法：

# 只有 10.0.0.0/8 网段的反代可信
memos --trusted-proxies 10.0.0.0/8 --data /var/opt/memos
# 完全直连（无代理），防止伪造 XFF 头
memos --trusted-proxies none --data /var/opt/memos

六、数据存储类参数

6.1 `--data` / `MEMOS_DATA`

数据目录。默认值规则（0.31.0 源码实查 + 实测）：显式指定优先；未指定时若 /var/opt/memos 存在且可写则用它（官方 Compose 方案即此场景）；否则用当前工作目录 .。目录必须存在，不存在会启动失败（进程会先校验再建库）。目录三件套结构：

/var/opt/memos/
├── memos_prod.db        # SQLite 主库（含 memo/用户/设置等全部业务数据）
├── memos_prod.db-wal    # WAL 预写日志
├── memos_prod.db-shm    # 共享内存文件
└── assets/              # 附件目录（LOCAL 存储类型上传附件后出现）

WorkingDirectory 与 --data 一致时，相对路径与绝对路径行为相同；建议 systemd 里两处都写绝对路径 /var/opt/memos，避免目录漂移。

6.2 `--driver` / `MEMOS_DRIVER` 与 `--dsn` / `MEMOS_DSN`

数据库驱动四选一：sqlite（默认）/ mysql / postgres / d1。SQLite 不需要 DSN；选外部数据库必须给 --dsn 连接串，格式按驱动而异：

# PostgreSQL（URI 形态）
memos --driver postgres --dsn "postgresql://memos:q1w2e3r4@db-host:5432/memos?sslmode=disable" --data /var/opt/memos
# MySQL（Go 驱动 DSN 形态）
memos --driver mysql --dsn "memos:q1w2e3r4@tcp(db-host:3306)/memos" --data /var/opt/memos

💡 技术拓展：四种驱动的取舍——

驱动原理/特点适用场景
sqlite 单文件嵌入式库，零依赖，随数据目录整体备份个人/小团队单实例（默认推荐）
mysql 外部关系库，复制/备份体系成熟已有 MySQL 运维体系
postgres 外部关系库，类型系统与扩展更现代团队多用户中等规模
d1 Cloudflare 边缘数据库适配（wasm 构建）边缘/Serverless 特殊形态

单实例自托管用默认 SQLite 即可；需要数据库级高可用、独立备份或多人共享数据源时上 PostgreSQL/MySQL。

驱动	原理/特点	适用场景
sqlite	单文件嵌入式库，零依赖，随数据目录整体备份	个人/小团队单实例（默认推荐）
mysql	外部关系库，复制/备份体系成熟	已有 MySQL 运维体系
postgres	外部关系库，类型系统与扩展更现代	团队多用户中等规模
d1	Cloudflare 边缘数据库适配（wasm 构建）	边缘/Serverless 特殊形态

驱动切换的排障实录：选了外部驱动却不给 DSN，程序会按各自驱动默认值连「本机」，实测 --driver mysql 不带 DSN 的完整报错：

time=2026-10-22T08:54:49.988+08:00 level=ERROR msg="memos failed" error="failed to migrate database: failed to pre-migrate: failed to check if database is initialized: failed to check if database is initialized: Error 1045 (28000): Access denied for user ''@'localhost' (using password: NO)"

看到 Access denied for user ''@'localhost' 即为「DSN 缺失」的指纹：补全 --dsn 重启即可。另外 --demo 与外部驱动互斥，实测 --demo --driver postgres：

time=2026-10-22T08:54:49.943+08:00 level=ERROR msg="memos failed" error="failed to validate profile: demo mode requires the sqlite database driver, got \"postgres\""

七、运行模式与安全类参数

7.1 `--demo` / `MEMOS_DEMO`

演示模式（仅限 sqlite 驱动，见 6.2 实测报错）。开启后启动日志会附加一行 Demo mode is enabled，实例行为面向公开演示（配合注册策略）。生产实例不要开启。

7.2 `--log-level` / `MEMOS_LOG_LEVEL`

日志级别 debug/info/warn/error，默认 info。日志直接输出到 stderr，systemd 场景由 journal 收集：

journalctl -u memos --no-pager -n 6

实测回显：

Oct 22 00:58:08 997a6dd867b0 systemd[1]: Started memos.service - Memos self-hosted memo service.
Oct 22 00:58:08 997a6dd867b0 memos[405]: Memos 0.31.0 started successfully!
Oct 22 00:58:08 997a6dd867b0 memos[405]: Data directory: /var/opt/memos
Oct 22 00:58:08 997a6dd867b0 memos[405]: Database driver: sqlite
Oct 22 00:58:08 997a6dd867b0 memos[405]: Server running on port 8081
Oct 22 00:58:08 997a6dd867b0 memos[405]: Access mode: private

排查迁移/存储问题时临时切 debug（启动日志形态不变，DEBUG 行出现在库操作等插桩路径），日常用 info；生产可用 warn 降噪。优雅停机日志（systemctl restart memos 触发 SIGTERM）：

time=2026-10-22T08:55:30.864+08:00 level=INFO msg="server shutting down"
time=2026-10-22T08:55:30.864+08:00 level=INFO msg="memos stopped properly"

7.3 `--rate-limit` / `MEMOS_RATE_LIMIT`

请求限流开关，默认开启。对登录等敏感端点按维度限流，实测（对登录接口连续 12 次错误密码尝试，第 11 次起被限流，返回 429）：

for i in $(seq 1 12); do curl -s -o /dev/null -w "%{http_code} " -X POST http://127.0.0.1:8081/api/v1/auth/signin -H "Content-Type: application/json" -d '{"passwordCredentials":{"username":"root","password":"wrongpass"}}'; done

实测回显：

400 400 400 400 400 400 400 400 400 400 429 429

公网实例保持默认开启；确需关闭（如内网压测）：--rate-limit=false，启动正常（实测回显与默认启动一致，仅限流器不生效）。

7.4 `--webhook-private-network-allowlist` 与废弃的 `--allow-private-webhooks`

webhook 目标默认禁止指向私网/保留地址（SSRF 防护）。确需让 webhook 调用内网服务（如自建自动化入口）时，把目标主机名/IP/CIDR 加入白名单：

memos --webhook-private-network-allowlist 10.0.0.5,notify.internal:8443 --data /var/opt/memos

0.31 之前的旧参数 --allow-private-webhooks（整体放开私网访问）已废弃但仍兼容，实测传入时的双重告警（Flag 告警 + WARN 日志）：

Flag --allow-private-webhooks has been deprecated, use --webhook-private-network-allowlist to allow only required destinations
time=2026-10-22T08:56:08.514+08:00 level=WARN msg="--allow-private-webhooks is deprecated and disables webhook private-network protection; use --webhook-private-network-allowlist"

存量脚本请尽快迁移到白名单参数，只放行确实需要的目的地址。

八、实例设置详解（存数据库的 7 组）

实例设置是 Memos 的「运行时可调配置」，Web 设置页可视化管理，API 端点为 GET/PATCH /api/v1/instance/settings/<KEY>，落库于 system_setting 表。三步通用操作（本节所有回显均在 8081 实测）：

# 1. 登录拿令牌（15 分钟有效，脚本内现取现用）
TOKEN=$(curl -s -X POST http://127.0.0.1:8081/api/v1/auth/signin -H "Content-Type: application/json" -d '{"passwordCredentials":{"username":"root","password":"q1w2e3r4"}}' | python3 -c "import json,sys; print(json.load(sys.stdin)['accessToken'])")
# 2. 读设置
curl -s http://127.0.0.1:8081/api/v1/instance/settings/ACCESS -H "Authorization: Bearer $TOKEN"
# 3. 改设置（PATCH，body 里 name 必填且与路径一致）
curl -s -X PATCH http://127.0.0.1:8081/api/v1/instance/settings/ACCESS -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -d '{"name":"instance/settings/ACCESS","accessSetting":{"accessMode":"INSTANCE_ACCESS_MODE_PUBLIC"}}'

第 2 步实测回显（默认私有）：

{"name":"instance/settings/ACCESS","accessSetting":{"accessMode":"INSTANCE_ACCESS_MODE_PRIVATE"}}

8.1 GENERAL：站点通用

字段全景（GET 默认值 + 实测 PATCH 效果）：

字段	默认值	说明
`disallowUserRegistration`	false	关闭自助注册（建好账号后建议改 true）
`disallowPasswordAuth`	false	关闭密码登录（SSO-only 部署用）
`additionalScript` / `additionalStyle`	空	全站注入的自定义 JS/CSS
`customProfile.title` / `.description` / `.logoUrl`	空	站点标题/描述/Logo
`weekStartDayOffset`	0	周起始日：0 周日…6 周六
`disallowChangeUsername` / `disallowChangeNickname`	false	禁止用户改名/改昵称

实测：关闭注册并设置站点标题（PATCH 后立即生效，回显节选）：

curl -s -X PATCH http://127.0.0.1:8081/api/v1/instance/settings/GENERAL -H "Content-Type: application/json" -H "Authorization: Bearer $TOKEN" -d '{"name":"instance/settings/GENERAL","generalSetting":{"disallowUserRegistration":true,"customProfile":{"title":"quzuo 实验室","description":"自托管闪念笔记"}}}' | python3 -m json.tool

实测回显（节选）：

{
    "name": "instance/settings/GENERAL",
    "generalSetting": {
        "disallowUserRegistration": true,
        "customProfile": {
            "title": "quzuo 实验室",
            "description": "自托管闪念笔记",
            "logoUrl": ""
        }
    }
}

8.2 STORAGE：附件存储

实测全新实例默认值：

{"name":"instance/settings/STORAGE","storageSetting":{"storageType":"LOCAL","filepathTemplate":"assets/{timestamp}_{uuid}_{filename}","uploadSizeLimitMb":"30","storages":[{"id":"local","name":"Local","type":"LOCAL"}],"defaultStorageId":"local"}}

字段	默认值	说明
`storageType`	LOCAL	旧版兼容字段（DATABASE/LOCAL/S3）
`filepathTemplate`	`assets/{timestamp}_{uuid}_{filename}`	附件落盘路径模板
`uploadSizeLimitMb`	30	单文件上传上限（MB）
`storages[]`	内置 local 一项	多命名存储实例列表（LOCAL/S3 可并存）
`defaultStorageId`	local	新附件使用的存储

💡 技术拓展：附件存储三形态——DATABASE（附件连同库文件一起备份，小规模最省心）、LOCAL（落 assets/ 目录，便于文件级同步但需单独备份该目录）、S3（S3 兼容对象存储，如 Cloudflare R2，配 endpoint/region/bucket/密钥，适合附件多、容量大的实例）。0.31 支持配置多个存储实例并为新附件指定默认项，历史附件保留其原存储引用。

8.3 MEMO_RELATED：memo 行为

实测默认值：

{"name":"instance/settings/MEMO_RELATED","memoRelatedSetting":{"contentLengthLimit":8192,"enableDoubleClickEdit":false,"reactions":["👍","👎","❤️","🎉","😄","😕","😢","😡"]}}

字段	默认值	说明
`contentLengthLimit`	8192	单条 memo 内容长度上限（字节）
`enableDoubleClickEdit`	false	双击 memo 进入编辑
`reactions`	8 个内置 emoji	可用的表情反应集

⚠️ 注意：PATCH 是整组覆盖语义——请求体里未带的子字段会被清空。实测给 MEMO_RELATED 只提交 contentLengthLimit 与 enableDoubleClickEdit 时，回显中 reactions 变成了空数组：

{
    "name": "instance/settings/MEMO_RELATED",
    "memoRelatedSetting": {
        "contentLengthLimit": 8192,
        "enableDoubleClickEdit": true,
        "reactions": []
    }
}

正确做法是先 GET 拿全量 JSON，在返回体上改需要的字段再原样 PATCH 回去。

8.4 TAGS / NOTIFICATION / AI

TAGS：标签元数据表（tags: {标签名: {backgroundColor, blurContent}}），支持锚定正则匹配标签名（如 project/.* 命中整个前缀）；0.31 起活跃元数据实际存于各用户的标签设置，该组设置保留用于兼容与迁移。
NOTIFICATION：SMTP 邮件通道（email.enabled/smtpHost/smtpPort/smtpUsername/smtpPassword/fromEmail/fromName/replyTo/useTls/useSsl），配置后实例可发通知邮件；密码字段只写不读（API 回显不返回明文）。
AI：提供商列表（type: OPENAI | GEMINI + endpoint + api_key，密钥只写不读、回显仅给掩码提示 api_key_hint）与语音转写配置（transcription.providerId/model/language/prompt；不配置时转写关闭；OPENAI 默认模型 whisper-1，GEMINI 默认 gemini-2.5-flash，源码实查）。

8.5 设置的三个视图与优先级

同一设置在三个位置可能出现：数据库 system_setting（Web/API 写入的「存储配置」）、/etc/secrets/memos-instance-setting-<key>.json（部署配置文件）、运行时生效值。规则（官方 configuration-provisioning 设计文档 + 实测）：文件配置遮蔽（shadow）同名存储配置，文件里有的键以文件为准且 API 写入无法改变其生效值；删除文件并重启后恢复数据库值；文件配置进程启动时一次性装载快照，改文件必须重启。

实测（挂载 /etc/secrets 并放入 memos-instance-setting-access.json 声明 PUBLIC）：

systemctl restart memos
journalctl -u memos --no-pager -n 8 | grep -E "deployment|Access"

实测回显：

level=INFO msg="loaded deployment configuration" identityProviders=0 instanceSettings=1
Access mode: public

curl -s http://127.0.0.1:8081/api/v1/instance/profile | grep -o '"accessMode":"[^"]*"'

实测回显：

"accessMode":"INSTANCE_ACCESS_MODE_PUBLIC"

删除文件再重启即回退到数据库值（实测回退后 accessMode: INSTANCE_ACCESS_MODE_PRIVATE）。文件命名规范与字段校验见部署篇第八章。

九、生产配置模板

模板 A：个人 / 小团队（2 核 4GB，NVMe SSD，SQLite）——最简形态，/etc/systemd/system/memos.service：

[Unit]
Description=Memos self-hosted memo service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/var/opt/memos
ExecStart=/usr/local/bin/memos --data /var/opt/memos --port 8081 --instance-url "http://192.168.146.128:8081"
Environment=TZ=Asia/Shanghai
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

配套动作：注册完成后把 GENERAL 的 disallowUserRegistration 改为 true；备份用 sqlite3 .backup 每日热备；该形态实测空闲内存 15MiB 上下（systemctl status memos 的 Memory 字段实查 Memory: 15.2M (peak: 16.6M)），2GB 内存亦可承载。

模板 B：团队（4 核 8GB，SSD，PostgreSQL）——systemd 单元改用环境变量注入数据库连接：

[Unit]
Description=Memos self-hosted memo service
After=network.target postgresql.service

[Service]
Type=simple
User=root
WorkingDirectory=/var/opt/memos
ExecStart=/usr/local/bin/memos --data /var/opt/memos --port 8081
Environment=MEMOS_DRIVER=postgres
Environment=MEMOS_DSN=postgresql://memos:q1w2e3r4@db-host:5432/memos?sslmode=disable
Environment=MEMOS_INSTANCE_URL=https://memos.example.com
Environment=TZ=Asia/Shanghai
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

⚠️ 注意：Environment= 每行只能写一个变量；DSN 含特殊字符时整值加双引号。模板 B 的备份体系在数据库侧（pg_dump），/var/opt/memos 仍需随附件一起备份。验证配置生效：

systemctl daemon-reload && systemctl restart memos && systemctl is-active memos
journalctl -u memos -n 8 --no-pager | grep "Database driver"

实测回显：

active
Database driver: postgres

十、常见问题（FAQ）

Q1：端口到底是 5230 还是 8081？ 二进制默认 8081（--port 默认值，本篇全文实测即 8081）；官方 Compose 方案预置 MEMOS_PORT=5230，编排部署按其配置就是 5230。两边都可以用同名参数/环境变量改。

Q2：老版本资料里的 MEMOS_MODE=prod 怎么不管用了？ 0.31.0 已无 mode 参数（--help 全量实查无此项），生产/开发模式之分随 0.31 重构移除，无需设置；从旧版升级时从启动脚本里删掉 MEMOS_MODE 即可（留着也只是无效环境变量）。

Q3：改了环境变量不生效？ 两个常见原因：① systemd 单元里加 Environment= 后忘了 systemctl daemon-reload + restart；② 与命令行参数同名时，显式传入的参数优先级更高（第三章优先级实测），检查 ExecStart 是否已带同名参数。

Q4：PATCH 设置后其他字段被清空？ PATCH 是整组覆盖（8.3 节实测 reactions 被清空），先 GET 全量再增量修改后整体提交。

Q5：--instance-url 启动报错？ 只接受 http/https 协议（5.4 节实测 ftp:// 被拒）。反代 + HTTPS 部署时写 https://memos.example.com，不要带路径后缀。

Q6：时间显示差 8 小时？ 进程时区问题。systemd 单元加 Environment=TZ=Asia/Shanghai（模板 A/B 已含），systemctl restart memos 后生效；库内时间戳本就按 UTC 存储，只影响展示。

Q7：升级 0.31 后 Shortcuts 集成挂了 / RSS 没了？ 0.31 的两个不兼容变更：Shortcuts API 由 UserService 的 View 操作（/api/v1/users/{user}/views）取代，RSS 订阅源已整体移除（官方 CHANGELOG 明确）。第三方集成需按新 API 改造，依赖 RSS 输出的场景需另行规划。

十一、参考链接

官方部署与环境变量文档：https://usememos.com/docs/deploy
v0.31.0 源码（参数定义 cmd/memos/main.go、默认值 internal/profile/profile.go）：https://github.com/usememos/memos/tree/v0.31.0
配置装载（configuration provisioning）设计文档：https://github.com/usememos/memos/blob/v0.31.0/docs/configuration-provisioning.md
0.31.0 CHANGELOG（不兼容变更清单）：https://github.com/usememos/memos/blob/v0.31.0/CHANGELOG.md
官方二进制下载：https://github.com/usememos/memos/releases/tag/v0.31.0
本专栏相关篇章：《Memos 介绍与选型指南》、《Memos 0.31.0 Docker Compose 部署指南》、《Memos 0.31.0 常用 CLI 命令与工具详解》

Memos 0.31.0 配置参数详解

Memos 0.31.0 配置参数详解

一、环境信息

二、前置条件

三、参数查看与修改方式

四、参数总览

五、服务监听与网络类参数

5.1 --port / MEMOS_PORT

5.2 --addr / MEMOS_ADDR

5.3 --unix-sock / MEMOS_UNIX_SOCK

5.4 --instance-url / MEMOS_INSTANCE_URL

5.5 --trusted-proxies / MEMOS_TRUSTED_PROXIES

六、数据存储类参数

6.1 --data / MEMOS_DATA

6.2 --driver / MEMOS_DRIVER 与 --dsn / MEMOS_DSN

七、运行模式与安全类参数

7.1 --demo / MEMOS_DEMO

7.2 --log-level / MEMOS_LOG_LEVEL

7.3 --rate-limit / MEMOS_RATE_LIMIT

7.4 --webhook-private-network-allowlist 与废弃的 --allow-private-webhooks

八、实例设置详解（存数据库的 7 组）

8.1 GENERAL：站点通用

8.2 STORAGE：附件存储

8.3 MEMO_RELATED：memo 行为

8.4 TAGS / NOTIFICATION / AI

8.5 设置的三个视图与优先级

九、生产配置模板

十、常见问题（FAQ）

十一、参考链接

5.1 `--port` / `MEMOS_PORT`

5.2 `--addr` / `MEMOS_ADDR`

5.3 `--unix-sock` / `MEMOS_UNIX_SOCK`

5.4 `--instance-url` / `MEMOS_INSTANCE_URL`

5.5 `--trusted-proxies` / `MEMOS_TRUSTED_PROXIES`

6.1 `--data` / `MEMOS_DATA`

6.2 `--driver` / `MEMOS_DRIVER` 与 `--dsn` / `MEMOS_DSN`

7.1 `--demo` / `MEMOS_DEMO`

7.2 `--log-level` / `MEMOS_LOG_LEVEL`

7.3 `--rate-limit` / `MEMOS_RATE_LIMIT`

7.4 `--webhook-private-network-allowlist` 与废弃的 `--allow-private-webhooks`