OnionShare 2.7.1 配置参数详解

目标：把 OnionShare 2.7.1 CLI（onionshare-cli）的三层配置体系——命令行参数、全局配置文件、持久会话文件——逐项拆解到位，每个字段给出真实默认值与实测验证方式。全文参数均已在 Ubuntu 22.04 + OnionShare 2.7.1 实测环境逐条验证；安装步骤见本专栏 《Ubuntu 22.04 安装 OnionShare 2.7.1 指南》，命令行用法全貌见本专栏 《OnionShare 2.7.1 常用 CLI 命令详解》。

一、环境信息

二、前置条件

本篇的所有「查看/修改/验证」动作都基于已安装可用的 CLI，先完成安装与 Tor 接入（见 《Ubuntu 22.04 安装 OnionShare 2.7.1 指南》第四、七章）。快速自检：

onionshare-cli --help 2>&1 | grep "v2.7.1"

实测回显：

│                  v2.7.1                   │

三、参数查看与修改方式

OnionShare CLI 的配置分三层，优先级与用途各不相同，实测梳理如下。

3.1 第一层：命令行参数（一次性生效）

onionshare-cli --help 列出的全部参数只在本次进程生效，不改任何文件。查看全量参数：

onionshare-cli --help

实测回显（输出节选，实测首尾；完整逐参详解见命令篇）：

usage: onionshare-cli [-h] [--receive] [--website] [--chat] [--local-only]
                      [--connect-timeout SECONDS] [--config FILENAME]
                      [--persistent FILENAME] [--title TITLE] [--public]
                      [--auto-start-timer SECONDS] [--auto-stop-timer SECONDS]
                      [--no-autostop-sharing] [--log-filenames] [--qr]
                      [--data-dir data_dir] [--webhook-url webhook_url]
                      [--disable-text] [--disable-files]
                      [--max-upload-size size] [--max-upload-size-total]
                      [--disable_csp] [--custom_csp custom_csp] [-v]
                      [filename ...]

3.2 第二层：全局配置文件（持久生效）

路径固定为 ~/.config/onionshare/onionshare.json（Linux）。这个文件不会自动创建——CLI 不带 --config 且文件不存在时使用内置默认值；需要持久化自定义时手工创建，或用 --config <自定义路径> 显式指定另一份配置。实测创建并生效（完整步骤与回显见安装篇 7.2 节）：

cat > /root/.config/onionshare/onionshare.json <<'EOF'
{
  "connection_type": "control_port",
  "control_port_address": "127.0.0.1",
  "control_port_port": 9051,
  "socks_address": "127.0.0.1",
  "socks_port": 9050,
  "auth_type": "no_auth",
  "auth_password": "",
  "bridge_use": false
}
EOF

修改后无需重启任何守护进程——onionshare-cli 每次启动时读取，退出后下次启动生效。

3.3 第三层：持久会话文件（地址固定化）

--persistent <文件> 指定的会话文件记录 onion 私钥与各模式参数，实现「重启后地址不变」。不传文件名时默认存入 ~/.config/onionshare/persistent/。实测目录（CLI 自动创建）：

/root/.config/onionshare/
└── persistent/

三层配置的分工：命令行参数覆盖一切（单次试验、临时调整）；全局配置管「Tor 连接方式」这类与具体分享无关的稳定项；持久会话管「这个服务的地址与模式开关」。同一项设置同时出现时，命令行参数 > 会话文件 > 全局配置。

四、参数总览

持久会话文件是字段最全的配置载体（含全部模式的状态字段）。以下是实测跑通持久分享后得到的会话文件原文：

{
  "onion": {
    "private_key": "SIJb/EsJMSH2rzaVGDz6n0Mr8lZtbb/4c2ao1mwZN0jbKeShtoVfODPV36rHD3iXfyoiCy96DtmPUzn22SGXjw==",
    "client_auth_priv_key": null,
    "client_auth_pub_key": null
  },
  "persistent": {
    "mode": "share",
    "enabled": true,
    "autostart_on_launch": false
  },
  "general": {
    "title": null,
    "public": true,
    "autostart_timer": 0,
    "autostop_timer": 0,
    "service_id": "xmxemi643l2zxkv2qkkkn5nlkpavrwreg4ivdyqqmuiewtx467zfy5qd",
    "qr": false
  },
  "share": {
    "autostop_sharing": true,
    "filenames": [
      "/share/notes.txt"
    ],
    "log_filenames": false
  },
  "receive": {
    "data_dir": "/root/OnionShare",
    "webhook_url": null,
    "disable_text": false,
    "disable_files": false,
    "max_upload_size": 0,
    "max_upload_size_total": false,
    "total_upload_size": 0
  },
  "website": {
    "disable_csp": false,
    "custom_csp": null,
    "log_filenames": false,
    "filenames": []
  },
  "download": {
    "data_dir": "/root/OnionShare",
    "poll": 0
  },
  "chat": {}
}

总览解读：

• 七个分组对应「连接/会话 + 五种模式」：onion（服务密钥）、persistent（会话开关）、general（跨模式公共项）、share/receive/website/download/chat（各模式专属）；
• null/0/false 均为实测默认值：未设标题、非公开外的默认时序、无 webhook、上传无大小限制等；
• service_id 是 56 字符 onion v3 地址的裸串（URL 前缀 http:// + service_id + .onion）；
• share.autostop_sharing: true 即官方默认「对方下载完成后自动停服」。

五、核心参数分类详解

5.1 连接组（connection_type / socks / auth / bridge）

Tor 连接方式只存于全局配置文件，决定 CLI 怎么接入 Tor 网络：

💡 技术拓展：CLI 接入 Tor 的连接方式不止 control_port 一种，主流方式对比——

方式	原理	适用场景
automatic	CLI 启动自己的 tor 子进程	能直连 Tor 的桌面/服务器，零配置
control_port	连接系统 tor 服务的控制端口	受限网络下已配好代理/网桥的系统 tor
socket_file	经 Unix domain socket 连接	systemd socket 激活形态的 tor

本文实测采用 control_port：受限网络下 tor 必须先经 Socks5Proxy 建链，CLI 再接管（完整实测步骤见安装篇第七章）。

5.2 通用组（general）

public 的实测对照：默认（false）启动输出含私钥（安装篇 4.5 节 local-only 回显有 Private key: 行），加 --public 后该行消失、仅输出地址（安装篇 7.2 节回显）。

5.3 share 组（文件分享）

5.4 receive 组（接收文件/消息）

data_dir 的实测验证：以 --local-only --data-dir /tmp/rcvd 启动后用 curl 上传，文件落在日期子目录（实测回显节选）：

Upload of total size 215.0 B is starting
=> 19.0 B up.txt

/tmp/rcvd/2026-10-31/  ← 按日期自动分目录

5.5 website 组（静态网站）

默认 CSP 的实测验证（curl -I 实测响应头节选）：

Content-Security-Policy: default-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; img-src 'self' data:;
Referrer-Policy: no-referrer
Server: OnionShare
X-Content-Type-Options: nosniff
X-Frame-Options: DENY

custom_csp 的实测对照——启动参数加 --custom_csp "default-src 'self' https://cdn.example.com" 后：

Content-Security-Policy: default-src 'self' https://cdn.example.com

即 CSP 头被整串替换。三者关系：默认安全头 → custom_csp 覆盖 → disable_csp 连头都不发（按需选用，公开站点慎关）。

5.6 download 组（2.7 新增下载模式）

5.7 onion 与 persistent 组（持久会话专属）

持久会话的典型实测排障：同一会话文件对应服务已在线时再次以 --persistent 启动，实测报错并退出：

Tor error: ADD_ONION response didn't have an OK status: Onion address collision

原因：一个 onion 私钥同时只能挂一个在线服务。先停掉旧进程再启动（详见命令篇第六章）。

六、生产配置模板

场景：4 核 8 GB、NVMe 磁盘、1 Gbps 出口的独立服务器，跑一个团队级常驻匿名收件箱（只收文件、限单次 500 MB、webhook 通知内部机器人）。

Tor 侧（/etc/tor/torrc 追加/修改项，受限网络含代理行）：

ControlPort 127.0.0.1:9051
CookieAuthentication 0
SocksPort 9050
# Socks5Proxy 192.168.1.72:7897   ← 仅 Tor 直连被阻断的网络才启用
DataDirectory /var/lib/tor

全局配置 /root/.config/onionshare/onionshare.json：

{
  "connection_type": "control_port",
  "control_port_address": "127.0.0.1",
  "control_port_port": 9051,
  "socks_address": "127.0.0.1",
  "socks_port": 9050,
  "auth_type": "no_auth",
  "auth_password": "",
  "bridge_use": false
}

启动参数（常驻服务，配合 systemd 单元见安装篇第八章）：

onionshare-cli --receive --public --data-dir /data/onionshare/inbox --max-upload-size 500mb --webhook-url http://127.0.0.1:8128/hook --disable-text

参数取舍说明：--public 免去访客导入私钥（收件箱场景地址通过既有渠道分发）；--data-dir 指到独立数据盘并配好属主；--max-upload-size 500mb 防滥用；--disable-text 纯收件场景关掉文字通道。磁盘占用随接收量线性增长，建议外部再配目录配额或定期清理。

七、常见问题（FAQ）

Q1：改了 onionshare.json 不生效？ 确认三件事：路径是否为运行用户的 ~/.config/onionshare/onionshare.json（root 运行就是 /root/.config/...）；JSON 是否合法（python3 -m json.tool <文件> 校验）；改配置只影响下一次启动，正在跑的服务不受影响。

Q2：配置里 auth_type 和 torrc 认证对不上会怎样？ CLI 连控制端口被拒，实测现象为 Can't connect to the Tor controller at <地址:端口>.。两边同步：torrc 用 Cookie 认证则 auth_type: cookie，用密码则 auth_type: password + auth_password。

Q3：--max-upload-size 100mb 收到的文件还是更大？ 检查 max_upload_size_total：若为 true，限额作用于服务整个生命周期的累计量而非单次。两个维度按需组合。

Q4：持久会话地址每次都变？ --persistent 传入的必须是同一个文件路径且文件可写；不传路径时默认落在 ~/.config/onionshare/persistent/ 下的模式命名文件。重启后地址不变的前提是私钥在会话文件里被复用。

Q5：能只改会话文件里的参数而不重启服务吗？ 不能。会话文件在启动时读取、停止时回写；运行中的服务以启动时快照为准，改文件对运行中服务无效。

八、参考链接

• OnionShare 2.7.1 官方文档 - Advanced Usage
• OnionShare 2.7.1 官方文档 - Features
• OnionShare GitHub 仓库
• 本专栏：《Ubuntu 22.04 安装 OnionShare 2.7.1 指南》、《OnionShare 2.7.1 常用 CLI 命令详解》、《OnionShare 介绍与选型指南》