Databag 0.1.18 配置参数详解

Databag 服务端 0.1.18 全部配置入口逐项详解：启动旗标、SQLite configs 表、管理 API，含全量覆盖与开放注册两大版本坑。

DatabagDatabag端到端加密即时通信自托管去中心化2026/10/25

Databag 0.1.18 配置参数详解

目标：把 Databag 0.1.18 服务端的全部配置入口（启动旗标、SQLite 配置表、管理 API）讲清并逐项实测。所有命令与回显来自 2026-10-25 在 Ubuntu 22.04 真实服务器上的实测（源码编译安装，路径按真实服务器惯例）。

一、环境信息

  • 操作系统：Ubuntu 22.04 LTS（amd64）
  • 组件版本：Databag 服务端 0.1.18（源码编译，二进制 /opt/databag/bin/databag）
  • 数据目录：/var/lib/databag（databag.db + 账号附件）
  • 配置载体：SQLite databag.db 的 configs 表（运行参数）+ 启动旗标（部署参数）
  • 服务管理：systemd（databag.service，监听 7000）

二、前置条件

三、参数查看与修改方式

Databag 的配置分两层，先认清层再动手：

层内容修改方式生效时机
启动旗标端口/目录/TLS 证书/转码脚本改 systemd unit 的 ExecStart 后重启重启进程
SQLite configs 表域名/配额/开关/MFA 等业务配置①管理台界面 ②PUT /admin/config ③sqlite3 直改实时（每次请求读库）

业务配置的三种改法，实测对比：

  • 管理台：浏览器 → 右上角齿轮 → 输口令 → 设置弹窗，适合日常维护；
  • 管理 API：PUT /admin/config，适合自动化（注意是全量覆盖语义，见 5.1 实测）；
  • sqlite3 直改：configs 表键值对，适合应急恢复与 API 覆盖不到的项（如 0.1.18 的开放注册开关，见常见问题 Q2）。改库前建议 systemctl stop databag 避免写竞争。

四、参数总览

4.1 启动旗标（进程级，来自 main.go 实测）

旗标默认值说明
-p443监听端口。社区部署惯例用 7000
-s/var/lib/databag数据目录（SQLite 库 + 附件）
-w/opt/databag/Web 前端静态文件目录
-t（空）媒体转码脚本目录；为空则 transformSupported=false，图片/视频附件不可生成缩略与转码
-c（空）TLS 证书路径（与 -k 成对，给了就走 HTTPS）
-k（空）TLS 私钥路径

启动日志会原样回显生效旗标，实测：

2026/10/25 04:37:01 using args: -s /var/lib/databag -w /opt/databag/web -p 7000 -t /opt/databag/transform

⚠️ 注意：旗标解析是「两两成对」读取（-p 7000 这种），每个旗标都必须带值，写 -p 不带值会导致后面的参数错位。

4.2 SQLite configs 表（业务级，实测 select 全量）

sqlite3 /var/lib/databag/databag.db "select config_id, str_value, num_value, bool_value from configs;"

实测回显（一台配好域名与配额的节点）：

asset_path|/var/lib/databag|0|0
script_path|/opt/databag/transform|0|0
web_public_key|BEOMscZ1qsU5uD_z2tEGhzvsBbN_gcGYsglha66S7yparcdFPVkAHdBluxxTVjulXHK5rRGWsWcmoktNZ3ibTQg|0|0
web_private_key|9bfi_6tzeNQ3DUwcVXs1UrMjJDXWqGm74WZydalDvbU|0|0
domain|databag.example.com|0|0
storage||1073741824|0
enable_image||0|1
enable_audio||0|1
enable_video||0|1
enable_binary||0|1
allow_unsealed||0|1
push_notifications||0|0
key_type|RSA2048|0|0
enable_ice||0|0
ice_service||0|0
ice_url||0|0
ice_username||0|0
ice_password||0|0
token|q1w2e3r4||
configured|||1

表中每行是 config_id | str_value | num_value | bool_value，值落在哪个列取决于参数类型。

五、核心参数分类详解

5.1 节点身份与联邦

domain（字符串，默认空）——节点对外域名，联邦通信与账号发现的前提。管理 API 实测设置：

SESSION=$(curl -s -X PUT "http://127.0.0.1:7000/admin/access?token=q1w2e3r4" | tr -d '"')
curl -s -X PUT "http://127.0.0.1:7000/admin/config?token=$SESSION" \
  -H 'Content-Type: application/json' \
  -d '{"domain":"databag.example.com","accountStorage":1073741824,"allowUnsealed":true,"enableImage":true,"enableAudio":true,"enableVideo":true,"enableBinary":true,"keyType":"RSA2048","enableIce":false,"iceService":"","iceUrl":"","iceUsername":"","icePassword":""}'
curl -s "http://127.0.0.1:7000/admin/config?token=$SESSION"

回读实测：

{"domain":"databag.example.com","enableImage":true,"enableAudio":true,"enableVideo":true,"enableBinary":true,"enableIce":false,"iceService":"","iceUrl":"","iceUsername":"","icePassword":"","keyType":"RSA2048","accountStorage":1073741824,"transformSupported":true,"allowUnsealed":true,"pushSupported":false}

⚠️ 实测坑（全量覆盖语义）：PUT /admin/config 会把请求体里没带的字段全部重置为零值。实测只发 {"enableOpenAccess":true,"openAccessLimit":3} 后回读，domain 变空串、enableImage 等全变 false——等于一次配置清空。用 API 改配置必须带全量字段，管理台无此问题（它总是提交全量）。

key_type（字符串，默认 RSA2048）——新建账号身份密钥算法。

💡 技术拓展：账号身份密钥可选算法对比——

算法密钥长度特点
RSA20482048 位生成快（实测秒级），安全性满足常规场景
RSA40964096 位更抗暴力破解，生成明显更慢，低功耗设备慎选

该参数只影响新创建的账号；已存在账号的密钥不变。默认 RSA2048。

token / configured（系统项）——管理员口令与「已完成初始化」标记，即安装期预置的两行；口令重置见常见问题 Q1。

5.2 存储与配额

storage（整数，默认 0）——每个账号的存储配额（字节），0 = 不限。管理台显示为 GB 单位换算；API 里 accountStorage 字段直接传字节（如 1GiB = 1073741824）。

asset_path（字符串，默认 -s 目录）——账号附件存储根路径，一般不动；要把附件放大盘时可改并迁移既有子目录。

5.3 媒体类型开关

enable_image / enable_audio / enable_video / enable_binary（布尔，默认全 true）——控制账号可收发哪些类型的附件。关掉某类后，客户端上传该类附件会被拒。低配置节点（无 ffmpeg 环境）建议关 enable_video。

5.4 加密与隐私

allow_unsealed（布尔，默认 true）——是否允许创建「未密封」（非端到端加密）频道。纯私密节点建议设 false，强制全部频道 E2E。

💡 技术拓展：Databag 频道加密两种形态——

形态内容加密节点管理员可见性适用
密封（sealed）频道对称密钥 + 各账号 sealing 公钥包裹不可见内容私密通信默认
未密封（unsealed）不加密可见公告/公开频道类场景

本文示例节点保持默认 allow_unsealed=true（兼容官方客户端全部功能），隐私优先节点建议关闭。

5.5 推送

push_notifications（布尔，默认 true）——WebPush 推送总开关。web_public_key/web_private_key 是 VAPID 密钥对，首次启动自动生成，不要手工改；移动端推送还涉及 UnifiedPush/FCM/APN，在客户端侧选择通道。

5.6 音视频通话（WebRTC / ICE）

enable_ice（布尔，默认 false）+ ice_service/ice_url/ice_username/ice_password——TURN 中继配置。音视频通话靠 WebRTC，NAT 穿透必须有中继。

💡 技术拓展：ICE 中继常见选项——

选项形态特点
coturn 自建开源自建完全自控，需一台有公网 IP 的机器
Cloudflare TURN云服务免运维，按量计费
公共 STUN免费服务只打洞不中继，对称 NAT 下失败

官方 README 提供过一个演示 TURN（turn:34.210.172.114:3478 用户 user/pass），仅供测试，生产用前两者之一。

5.7 开放注册（open_access）

open_access（布尔，默认 false）+ account_limit（整数，默认 0 = 不限）——开启后任何人访问节点地址即可自助注册，无需管理员发创建链接。名额判定：当前账号数 < 限额（或限额为 0）即可注册，GET /account/available 返回剩余名额。

# 查询剩余可注册名额（无需令牌）
curl -s "http://127.0.0.1:7000/account/available"

1

⚠️ 0.1.18 实测坑：PUT /admin/config 接受 enableOpenAccess/openAccessLimit 字段但不落库（main 分支源码已接入该逻辑，0.1.18 发布版未含）。0.1.18 上开启开放注册的实测可行做法（停服后改库）：

systemctl stop databag
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id,bool_value) values ('open_access',1);"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id,num_value) values ('account_limit',10);"
systemctl start databag

实测改库后 /account/available 立即返回名额、免令牌注册成功。关闭同理把 bool_value 改 0。

5.8 管理员 MFA

mfa_enabled/mfa_confirmed（布尔）+ mfa_secret/mfa_algorithm（SHA1/SHA256，默认 SHA256）——管理台 TOTP 双因素认证。在管理台设置弹窗中开启并扫码绑定；开启后 PUT /admin/access 需额外带 code 参数（TOTP 六位码），连续失败会临时锁定（mfa_failed_time/mfa_failed_count 计数）。

5.9 会话与系统项（只读类）

admin_session（当前管理会话令牌，登录时刷新）、configured、web_public_key/web_private_key——系统自维护，不要手工修改。

六、生产配置模板

6.1 家庭私有节点（树莓派/NAS 级，2GB 内存）

{
  "domain": "im.home.example.com",
  "accountStorage": 536870912,
  "allowUnsealed": false,
  "enableImage": true,
  "enableAudio": true,
  "enableVideo": false,
  "enableBinary": false,
  "keyType": "RSA2048",
  "enableIce": false,
  "iceService": "",
  "iceUrl": "",
  "iceUsername": "",
  "icePassword": ""
}

要点：未密封频道关闭、视频附件关闭省转码开销、每账号 512MB 配额、不开音视频通话。

6.2 小团队节点（4GB VPS，含音视频）

{
  "domain": "chat.team.example.com",
  "accountStorage": 2147483648,
  "allowUnsealed": true,
  "enableImage": true,
  "enableAudio": true,
  "enableVideo": true,
  "enableBinary": true,
  "keyType": "RSA2048",
  "enableIce": true,
  "iceService": "turn",
  "iceUrl": "turn:turn.team.example.com:3478?transport=udp",
  "iceUsername": "databag",
  "icePassword": "q1w2e3r4"
}

要点：配额 2GB/账号、接自建 coturn 中继；管理员侧务必开启 MFA（5.8），并把管理台入口放在反向代理后用访问控制收敛。

七、常见问题

Q1：管理员口令忘了 / 要重置？ 停服 → 改库 → 起服：

systemctl stop databag
sqlite3 /var/lib/databag/databag.db "delete from configs where config_id='token'; delete from configs where config_id='configured';"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, str_value) values ('token', 'q1w2e3r4');"
sqlite3 /var/lib/databag/databag.db "insert into configs (config_id, bool_value) values ('configured', true);"
systemctl start databag

Q2：PUT /admin/config 后配置全丢了？ 该接口是全量覆盖不是局部补丁（5.1 实测）。恢复：按 5.1 的全量 JSON 重发一遍；日常改配置优先用管理台，用 API 必先 GET 回读、改字段后整体 PUT 回写。

Q3：改 configs 表需要重启吗？ 业务参数每次请求实时读库，不重启即生效；但 sqlite 直改与运行中服务并发写有概率冲突，稳妥做法是先 systemctl stop 再改。

Q4：-t 转码目录是什么、不挂会怎样？ -t 指向一组 shell 脚本（transform_ithumb.sh 图片缩略、transform_vhd.sh 视频转码等），调用 imagemagick/ffmpeg。不配置时 transformSupported=false，附件只能原样存取，无缩略图与转码。

八、参考链接