OnionShare 2.7.1 常用 CLI 命令详解

逐一实测 OnionShare 2.7.1 CLI 的五种模式与全部命令行参数，含真实启动回显、定时启停、二维码、持久会话与典型排障实录，作为服务器端操作的命令手册。

OnionShareOnionShareTor文件分享2026/10/31

OnionShare 2.7.1 常用 CLI 命令详解

目标：把 onionshare-cli 2.7.1 的五种服务模式与全部命令行参数逐一实测——每条命令都给出真实启动回显、行为差异与排障实录，作为服务器端命令手册使用。全文已在 Ubuntu 22.04 + OnionShare 2.7.1 环境逐条执行验证；安装与 Tor 接入见 《Ubuntu 22.04 安装 OnionShare 2.7.1 指南》，各字段的配置文件形态见 《OnionShare 2.7.1 配置参数详解》。

一、环境信息

项目实测值
操作系统Ubuntu 22.04.5 LTS（amd64）
OnionShare CLI2.7.1（启动横幅 v2.7.1）
Tor0.4.9.11（ControlPort 9051，已建链）
CLI 数据目录/root/.config/onionshare/
演示文件/root/hello.txt、/root/notes.txt
演示站点目录/root/site/（含 index.html）

二、工具概览

OnionShare CLI 只有一个可执行文件 onionshare-cli，一个命令内通过模式开关切换五种服务形态，Tor（系统 tor 或 CLI 自动拉起的子进程）负责建链：

模式开关服务形态一句话行为
（默认）Share 分享文件发文件，对方下载完成后自动停服
--receiveReceive 接收匿名收文件/文字，落盘到家目录
--websiteWebsite 网站托管纯静态站点
--chatChat 聊天开一个无日志临时聊天室
--local-only（调试修饰）不接 Tor，服务直接落在本机随机端口

启动横幅（所有模式共用，实测原文）：

╭───────────────────────────────────────────╮
│    *            ▄▄█████▄▄            *    │
│               ▄████▀▀▀████▄     *         │
│              ▀▀█▀       ▀██▄              │
│      *      ▄█▄          ▀██▄             │
│           ▄█████▄         ███        -+-  │
│             ███         ▀█████▀           │
│             ▀██▄          ▀█▀             │
│         *    ▀██▄       ▄█▄▄     *        │
│ *             ▀████▄▄▄████▀               │
│                 ▀▀█████▀▀                 │
│             -+-                     *     │
│   ▄▀▄               ▄▀▀ █                 │
│   █ █     ▀         ▀▄  █                 │
│   █ █ █▀▄ █ ▄▀▄ █▀▄  ▀▄ █▀▄ ▄▀▄ █▄▀ ▄█▄   │
│   ▀▄▀ █ █ █ ▀▄▀ █ █ ▄▄▀ █ █ ▀▄█ █   ▀▄▄   │
│                                           │
│                  v2.7.1                   │
│                                           │
│          https://onionshare.org/          │
╰───────────────────────────────────────────╯

⚠️ 注意：onionshare-cli 没有 --version 参数，版本号以横幅中的 v2.7.1 为准（实测 --version 返回 error: unrecognized arguments: --version）。

三、前置条件

  1. 已按 《Ubuntu 22.04 安装 OnionShare 2.7.1 指南》完成安装并打通 Tor 接入（控制端口路径或直连 automatic）；
  2. 验证 CLI 可用：
onionshare-cli --help 2>&1 | grep "v2.7.1"

实测回显：

│                  v2.7.1                   │
  1. 准备演示文件：
echo "OnionShare CLI demo" > /root/hello.txt
echo "OnionShare notes" > /root/notes.txt
mkdir -p /root/site
printf '<!doctype html><html><head><meta charset=utf-8><title>Demo</title></head><body><h1>OnionShare Website Demo</h1></body></html>' > /root/site/index.html

四、命令行参数总览

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 ...]

positional arguments:
  filename                  List of files or folders to share

options:
  -h, --help                show this help message and exit
  --receive                 Receive files
  --website                 Publish website
  --chat                    Start chat server
  --local-only              Don't use Tor (only for development)
  --connect-timeout SECONDS
                            Give up connecting to Tor after a given amount of
                            seconds (default: 120)
  --config FILENAME         Filename of custom global settings
  --persistent FILENAME     Filename of persistent session
  --title TITLE             Set a title
  --public                  Don't use a private key
  --auto-start-timer SECONDS
                            Start onion service at scheduled time (N seconds
                            from now)
  --auto-stop-timer SECONDS
                            Stop onion service at schedule time (N seconds
                            from now)
  --no-autostop-sharing     Share files: Continue sharing after files have
                            been sent (default is to stop sharing)
  --log-filenames           Log file download activity to stdout
  --qr                      Display a QR code in the terminal for share links
  --data-dir data_dir       Receive files: Save files received to this
                            directory
  --webhook-url webhook_url
                            Receive files: URL to receive webhook
                            notifications
  --disable-text            Receive files: Disable receiving text messages
  --disable-files           Receive files: Disable receiving files
  --max-upload-size size    Receive files: Maximum size of an upload, e.g.
                            100mb (0 means no limit)
  --max-upload-size-total   Receive files: Apply the maximum upload size to
                            the entire service lifespan
  --disable_csp             Publish website: Disable the default Content
                            Security Policy header (allows your website to use
                            third-party resources)
  --custom_csp custom_csp   Publish website: Set a custom Content Security
                            Policy header
  -v, --verbose             Log OnionShare errors to stdout, and web errors to
                            disk

参数速读：--connect-timeout 官方默认 120 秒；--max-upload-size 默认 0（不限）；五个模式开关互斥共用一个进程。参数与配置文件的映射关系见 《OnionShare 2.7.1 配置参数详解》第四章。

五、核心模式详解

5.1 share：分享文件（默认模式）

语法：onionshare-cli [选项] <文件/目录>...

默认形态（带私钥保护）：

onionshare-cli /root/hello.txt

实测回显（输出节选，实测首尾）：

Preparing file.

Give this address and private key to the recipient:
http://pzml3jle6djjzre2zboqcx2vv4qjptmnxpgoyfqun2ncqst4lgcykiyd.onion
Private key: WQPMCPM43RANUYKAWPAMIVZR6EYKNEJMB5HFYK7LGYQACD6FJXMA

Press Ctrl+C to stop the server

要点：默认是「地址 + 私钥」双因子，访客需在 Tor Browser 里同时导入两者；Private key 是 52 字符大写串。对方下载完成后服务自动停止，实测停止回显：

Stopped because transfer is complete

公开分享（--public）：

onionshare-cli /root/hello.txt --public

实测回显（输出节选，实测首尾）：

Preparing file.

Give this address to the recipient:
http://7ca2rxkrapck4xrdqt7n5zb2uf5ty37wtacvjcoxsqdz2uudb4oerbad.onion

Press Ctrl+C to stop the server

对照默认形态：提示语从 "address and private key" 变为 "address"，Private key 行消失——知道地址即可访问，适合挂在既有渠道分发的下载入口。

持续分享（--no-autostop-sharing）：默认「传完即停」，加该参数后允许多人多次下载：

onionshare-cli /root/hello.txt --public --no-autostop-sharing

启动回显与 --public 形态一致，差异在下载完成后的行为：不打印 Stopped because transfer is complete，服务保持在线（需 Ctrl+C 或 --auto-stop-timer 收尾）。

下载活动记录（--log-filenames）：有人在下载时于 stdout 打印活动行，配合 -v 或 systemd 日志留痕。

5.2 receive：匿名接收文件/消息

onionshare-cli --receive

实测回显（输出节选，实测首尾）：

Files sent to you appear in this folder: /root/OnionShare

Warning: Receive mode lets people upload files to your computer. Some files can potentially take control of your computer if you open them. Only open things from people you trust, or if you know what you are doing.

Give this address and private key to the sender:
http://7pgtmnofr4i4jm3cbmumxkgcqnicgw5zranp65ht4uaaadwrfaercgid.onion
Private key: CVDXBNW5EA6IUDCFBQ6HADIW5QIBRB3ZUCY7NWRA2RZ46IPQFHNQ

Press Ctrl+C to stop the server

要点：默认收件目录 /root/OnionShare/（按日期子目录存放）；官方安全警告提醒「上传文件可能恶意，谨慎打开」。

上传行为实测（--local-only --data-dir /tmp/rcvd 起服务后用 curl 模拟上传）：

curl -s -F "file=@/tmp/up.txt" http://127.0.0.1:<端口>/upload

服务端 stdout 实测回显：

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

落盘结果实测：

/tmp/rcvd/2026-10-31/    ← 按「日期」自动分目录，文件原样保存

接收域参数组合（只收文件不收文字、限额、webhook、标题）：

onionshare-cli --receive --disable-text --max-upload-size 500mb --data-dir /data/inbox --webhook-url http://127.0.0.1:8128/hook --title "Ops Team Drop Box"

实测启动回显（输出节选，实测首尾）：

Files sent to you appear in this folder: /root/OnionShare

Warning: Receive mode lets people upload files to your computer. ...

Give this address and private key to the sender:
http://127.0.0.1:17607
Private key: E2GOT5LTUTP3OAMRCRXO4GSH6VKJEUOXZQUC336SRKAHTTT5OVSA

Press Ctrl+C to stop the server

（上例以 --local-only 复演故地址为本机端口；联网形态输出 *.onion 地址，结构一致。）--disable-text 生效后访客页面不再提供文字通道；--max-upload-size 支持 mb/gb 单位，0 为不限。

5.3 website：托管静态站点

onionshare-cli --website /root/site

实测回显（输出节选，实测首尾）：

Give this address and private key to the recipient:
http://mvf2rcdhhxnjrkdmjtjvlndhgssexmgtvtwuwglytvpuadl36h7adcid.onion
Private key: AZKFJRNIV4NJZ3HUU64FC3MGTDEV33QICLGXZNQMKE6BIMQBBS2A

Press Ctrl+C to stop the server

默认安全响应头实测（curl -I 访问站点根路径）：

HTTP/1.1 200 OK
Content-Disposition: inline; filename=index.html; filename*=UTF-8''index.html
Content-Length: 125
Content-Security-Policy: default-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; img-src 'self' data:;
Content-Type: text/html
Referrer-Policy: no-referrer
Server: OnionShare
Via: OnionShare
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
X-Xss-Protection: 1; mode=block

默认 CSP 禁止加载第三方资源；站点确需 CDN 时用 --custom_csp 整串替换，实测对照（--custom_csp "default-src 'self' https://cdn.example.com"）：

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

或者 --disable_csp 连 CSP 头都不发送（公开站点慎用）。目录里没有 index.html 时改为列目录浏览。

5.4 chat：匿名聊天室

onionshare-cli --chat

实测回显（输出节选，实测首尾）：

Give this address and private key to the recipient:
http://6rzvznoi64l4tyjfcnuw5r66gufyktdfifhopwgbmdsdkdjwctroiryd.onion
Private key: 6A64Z35QRKRZHCP6Y6GJNF7HSDVAH2DG4A254FSTA3CWXCPJFXIQ

Press Ctrl+C to stop the server

要点：聊天室不落任何历史，访客用 Tor Browser 打开地址（非公开模式需先导入私钥）后以随机昵称进房；页面需要 JavaScript，Tor Browser 安全级别须为 Standard 或 Safer。

5.5 local-only：本地调试模式

onionshare-cli /root/hello.txt --local-only

实测回显（输出节选，实测首尾）：

Preparing file.

Give this address and private key to the recipient:
http://127.0.0.1:17649
Private key: E2GOT5LTUTP3OAMRCRXO4GSH6VKJEUOXZQUC336SRKAHTTT5OVSA

Press Ctrl+C to stop the server

--local-only 跳过 Tor，把 Web 服务直接暴露在 127.0.0.1:<随机端口>——隔离变量排障的利器：local-only 正常而正常模式失败，问题必然在 Tor 接入层（参考安装篇 7.1 节实测与第七章 FAQ）。官方注明该参数仅供开发调试，勿对外服务。

六、高级参数详解

6.1 --persistent：固定 onion 地址

--persistent <文件> 把服务固化为持久会话：私钥存入会话文件，重启进程后地址不变：

onionshare-cli /root/notes.txt --public --persistent /root/session.json

正常启动后地址与首次一致。会话文件内容（实测原文，字段解析见 《OnionShare 2.7.1 配置参数详解》第五.7 节）：

{
  "onion": { "private_key": "SIJb/EsJMSH2rzaVGDz6n0Mr8lZtbb/4c2ao1mwZN0jbKeShtoVfODPV36rHD3iXfyoiCy96DtmPUzn22SGXjw==", ... },
  "persistent": { "mode": "share", "enabled": true, "autostart_on_launch": false },
  "general": { "title": null, "public": true, "service_id": "xmxemi643l2zxkv2qkkkn5nlkpavrwreg4ivdyqqmuiewtx467zfy5qd", ... }
}

排障实录：Onion address collision。同一会话文件的服务已在线时再次以 --persistent 启动，实测直接报错退出（exit 0 前打印）：

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

定位：一个 onion 私钥同时只能注册一个在线服务，旧进程还挂着。解决：找到并停止旧进程（ps -ef | grep onionshare-cli）后再启动；配合 systemd 托管时保证单实例（安装篇第八章）。

6.2 --auto-stop-timer / --auto-start-timer：定时启停

定时停止实测（60 秒后自动下线）：

onionshare-cli /root/notes.txt --public --auto-stop-timer 60

实测回显（输出节选，实测首尾；等待 60 秒后）：

Preparing file.

Give this address to the recipient:
http://wftdwtyx4nvfkitlq23cbfgdnrny6ktsmv5xuhrmtujfct3gfjwf6jqd.onion

Press Ctrl+C to stop the server
Stopped because auto-stop timer ran out

Stopped because auto-stop timer ran out 即定时触发的自动停止（实测进程以 0 退出）。--auto-start-timer N 反之：先不发布，N 秒后才上线服务。二者可与持久会话叠加（定时 + 固定地址）。

6.3 --qr：终端二维码

onionshare-cli /root/hello.txt --public --qr

实测回显（输出节选，实测首尾）：

Give this address to the recipient:
http://zcviahdu4ceuewwgf3ynuolzgcniahucmuiumczha4tqjtgjbqgeryad.onion
Onion address as QR code:
    █▀▀▀▀▀█ ███▄ ▀  █▀█▄██ █▄   █ █▀▀▀▀▀█
    █ ███ █ ▄ ██▀▀ █▄▄ ▄▀ ▄▄ █▄█▄ █ ███ █
    █ ▀▀▀ █  ██▄█ ▄ ▄▀ █▄█▀  ▄█▀  █ ▀▀▀ █
    ▀▀▀▀▀▀▀ █ ▀▄▀ █ ▀▄█▄█ █ █ ▀ █ ▀▀▀▀▀▀▀
    ......（完整方块二维码，终端等宽字体下可扫描）

在地址行下方追加二维码，方便当面/截图分发。

6.4 --config / --connect-timeout / -v

  • --config <文件>：显式指定全局配置文件（不指定时读 ~/.config/onionshare/onionshare.json）。实测把 --config 指向一个控制端口写错的配置（9052 未监听）复现报错：

    Can't connect to the Tor controller at 127.0.0.1:9052.

    排障：核对配置文件 connection_type/control_port_port 与 tor 实际监听（安装篇 7.2 节探针命令验证）。

  • --connect-timeout SECONDS：连不上 Tor 的放弃阈值，官方默认 120 秒；受限网络排查时可调小快速失败（实测 20 秒超时在 7.1 节复现）。

  • -v / --verbose：把 OnionShare 内部错误打到 stdout、Web 错误落盘，排障时建议始终开着。

七、注意事项

  1. 进程前台阻塞：所有模式启动后都阻塞前台（Press Ctrl+C to stop the server），服务器常驻要配 systemd（安装篇第八章）或 nohup；
  2. Ctrl+C 立即下线：停止即从 onion 网络注销，无优雅下线缓冲；传输中强停会导致对方下载中断；
  3. 私钥即一切：Private key 与持久会话文件里的 private_key 都要按敏感凭据保管，泄露=地址被冒用；
  4. 多实例并存：同一 tor 上可以同时注册多个不同地址的服务（实测多模式并行无冲突），但同一持久会话只能单实例（见 6.1 collision 实录）；
  5. Receive 默认不设防：官方明确没有任何针对恶意上传文件的安全机制，收到的文件建议在隔离环境打开；
  6. 退出码：定时停止与 Ctrl+C 均以 0 退出，可放心接入 systemd Restart 策略之外的自定义脚本。

八、常见问题（FAQ）

Q1：启动卡在 Connecting to the Tor network: 5%/14% 后报 Taking too long to connect to Tor...？ Tor 直连被网络阻断的典型特征（实测回显见安装篇 7.1 节）。解决：给系统 tor 配 Socks5Proxy/网桥并改用控制端口连接（安装篇 7.2 节完整实测路径）。

Q2：报 Can't connect to the Tor controller at <地址:端口>.？ CLI 找不到 tor 控制端口（实测复现见 6.4 节）。核对 onionshare.json 与 torrc 的端口/认证一致性，并确认 tor 已建链（PROGRESS=100）。

Q3：报 Tor error: ADD_ONION response didn't have an OK status: Onion address collision？ 同一持久会话的旧服务还在线（实测实录见 6.1 节）。停旧进程再启动，或换新会话文件。

Q4：对方拿地址打不开？ 三查：服务是否还在前台跑（Ctrl+C 就下线了）；访客是否用 Tor Browser（.onion 地址普通浏览器无法解析）；非公开模式是否已导入 Private key。服务端可开 -v 看访问日志定位。

Q5：想让地址长期不变但又要定时启停？ --persistent 与 --auto-start-timer/--auto-stop-timer 可叠加，地址来自会话文件、启停只影响在线时段。

九、参考链接