Ubuntu 22.04 安装 OnionShare 2.7.1 指南

在 Ubuntu 22.04 服务器上从零安装 OnionShare 2.7.1 命令行版（onionshare-cli）与 Tor，覆盖在线 pip、离线 wheel 两套方案、Tor 受限网络接入配置与真实分享闭环验证。

OnionShareOnionShareTor文件分享2026/10/31

Ubuntu 22.04 安装 OnionShare 2.7.1 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 OnionShare 2.7.1 命令行版（onionshare-cli）及其依赖的 Tor，完成安装验证与真实 onion 服务发布闭环。本文所有命令与回显均已在 Ubuntu 22.04.5 LTS 实测环境逐条执行验证；软件定位与选型背景见 《OnionShare 介绍与选型指南》。

一、环境信息

本文实测环境的完整基线，所有版本号均来自真实环境的命令回显：

项目实测值获取命令
操作系统Ubuntu 22.04.5 LTS（amd64）cat /etc/os-release
Tor0.4.9.11（Ubuntu 官方仓库）tor --version
Python3.10.12python3 -V
pip22.0.2pip3 -V
OnionShare2.7.1（PyPI 包 onionshare-cli）启动横幅 v2.7.1
CLI 数据目录/root/.config/onionshare/运行时自动创建
默认收件目录/root/OnionShare/Receive 模式启动横幅
cat /etc/os-release | head -3   # 确认操作系统版本

实测回显：

PRETTY_NAME="Ubuntu 22.04.5 LTS"
NAME="Ubuntu"
VERSION_ID="22.04"

💡 技术拓展：OnionShare 的安装形态不止服务器 CLI 一种，主要发行形态对比——

形态获取方式适用场景
桌面应用官网 .msi/.dmg/Linux 打包个人电脑图形界面操作
CLI（onionshare-cli）PyPI pip install onionshare-cli服务器、无图形界面、脚本化
预装系统Tails/Qubes/Whonix/Parrot 内置开箱即用的匿名环境

本文采用 CLI 形态：服务器场景（收件箱、临时站点、脚本化分享）是唯一可行路径，也是官方文档 "Command-line only" 章节给出的标准安装方式。

二、前置条件

2.1 硬件与系统要求

OnionShare CLI 本身是 Python 进程，资源占用极低；真正的资源消耗在于 Tor 网络建链与文件传输。建议配置：2 核 CPU、2 GB 内存、20 GB 磁盘（Receive 模式按接收量另计）。无 Java 进程，无 JVM 调优项。

2.2 网络要求（重点）

  1. 安装期：能访问 Ubuntu 官方源 archive.ubuntu.com 与 PyPI（pypi.org）；
  2. 运行期：必须能接入 Tor 网络。国内网络环境通常无法直连 Tor——本文在受限网络下的实测表现与解法见第七章（Socks5Proxy 代理转发是实测可行路径）。

2.3 更新软件源索引

apt-get update

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

Get:15 http://archive.ubuntu.com/ubuntu jammy-updates/restricted amd64 Packages [8289 kB]
Get:16 http://archive.ubuntu.com/ubuntu jammy-updates/multiverse amd64 Packages [104 kB]
Get:17 http://archive.ubuntu.com/ubuntu jammy-backports/universe amd64 Packages [35.6 kB]
Get:18 http://archive.ubuntu.com/ubuntu jammy-backports/main amd64 Packages [82.9 kB]
Fetched 49.2 MB in 5s (10.0 MB/s)
Reading package lists...

三、版本选型说明

OnionShare 的 CLI 包在 PyPI 上以 onionshare-cli 名义发布，与桌面版同源同版本线。查询 PyPI 上的可用版本清单与最新稳定版：

pip3 index versions onionshare-cli

实测回显：

WARNING: pip index is currently an experimental command. It may be removed/changed in a future release without prior warning.
onionshare-cli (2.7.1)
Available versions: 2.7.1, 2.7, 2.6.5, 2.6.4, 2.6.3, 2.6.1, 2.6, 2.5, 2.3.3, 2.3.2, 2.3.1, 2.3
  INSTALLED: 2.7.1
  LATEST:    2.7.1

选型解读：

  • 2.7.1 是 PyPI 实测的最新稳定版（LATEST: 2.7.1），与官网下载页、官方文档站 2.7.1 版本线一致，本文按 2.7.1 安装；
  • 2.7 版本线新增了 Download 模式（在 OnionShare 内直接下载他人分享）等特性；2.6.x 及以下为旧线，无特殊兼容诉求不建议回退；
  • 版本分叉观察（官网桌面包 2.7.1 vs PyPI 页面快照 2.6/2.7 的差异）已在 《OnionShare 介绍与选型指南》第二章溯源，以 pip3 index versions 的实测清单为 CLI 侧准绳。

四、方案 A：在线 pip 安装（官方推荐）

4.1 方案说明

Ubuntu 官方仓库提供 Tor 与 python3-pip，PyPI 提供 onionshare-cli 主包与全部 Python 依赖。三步完成：装 Tor → 装 CLI → 验证。全程需外网（Ubuntu 源 + PyPI）。

4.2 安装 Tor 与 pip

DEBIAN_FRONTEND=noninteractive apt-get install -y tor python3-pip

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

Need to get 106 MB of archives.
Setting up tor (0.4.9.11-0ubuntu0.22.04.1) ...
Setting up torsocks (2.3.0-3) ...
Setting up tor-geoipdb (0.4.9.11-0ubuntu0.22.04.1) ...
Setting up python3-pip (22.0.2+dfsg-1ubuntu0.7) ...

验证 Tor 与 Python 环境：

tor --version
python3 -V
pip3 -V

实测回显：

Tor version 0.4.9.11.
Python 3.10.12
pip 22.0.2 from /usr/lib/python3/dist-packages/pip (python 3.10)

tor 二进制是 onionshare-cli 运行期的硬依赖：CLI 默认的 automatic 连接模式会自己拉起一个 tor 子进程来建链（见第七章实测），没有它 CLI 无法联网发布服务。

4.3 安装 onionshare-cli

pip3 install onionshare-cli==2.7.1

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

Collecting onionshare-cli==2.7.1
  Downloading onionshare_cli-2.7.1-py3-none-any.whl (162 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 162.2/162.2 KB 365.8 kB/s eta 0:00:00
Collecting requests[socks]>=2.32.3
  Downloading requests-2.34.2-py3-none-any.whl (73 kB)
......
Successfully built stem
Installing collected packages: stem, pypng, brotli, zope.interface, zope.event, waitress, urllib3, unidecode, typing-extensions, setuptools, pysocks, pycparser, psutil, pkgconfig, packaging, markupsafe, itsdangerous, idna, h11, greenlet, dnspython, cython, colorama, click, charset_normalizer, certifi, blinker, bidict, backports.zstd, wsproto, wheel, werkzeug, requests, qrcode, jinja2, gevent, eventlet, cffi, simple-websocket, pynacl, gevent-websocket, flask, python-engineio, flask-compress, python-socketio, flask-socketio, onionshare-cli
Successfully installed backports.zstd-1.8.0 bidict-0.23.1 blinker-1.9.0 brotli-1.2.1 certifi-2026.10.23 cffi-2.1.1 charset_normalizer-3.5.2 click-8.5.0 colorama-0.4.6 cython-3.3.0 dnspython-2.8.0 eventlet-0.41.3 flask-3.1.3 flask-compress-1.26 flask-socketio-5.7.0 gevent-26.9.0 gevent-websocket-0.10.1 greenlet-3.5.6 h11-0.16.0 idna-3.20 itsdangerous-2.2.0 jinja2-3.1.6 markupsafe-3.0.4 onionshare-cli-2.7.1 packaging-26.3 pkgconfig-1.6.0 psutil-7.2.2 pycparser-3.11 pynacl-1.6.2 pypng-0.20220715.0 pysocks-1.7.1 python-engineio-4.15.1 python-socketio-5.17.1 qrcode-7.4.2 requests-2.34.2 setuptools-84.2.1 simple-websocket-1.1.0 stem-1.8.1 typing-extensions-4.16.0 unidecode-1.4.0 urllib3-2.8.0 waitress-3.0.2 werkzeug-3.1.9 wheel-0.48.0 wsproto-1.3.2 zope.event-6.2 zope.interface-8.6
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv

要点解读：

  • 主包 onionshare_cli-2.7.1-py3-none-any.whl 仅 162 kB，但会连带安装 Flask/stem/gevent 等 47 个 Python 依赖（stem 是 Tor 控制协议库，负责与 Tor 通信）；
  • 回显中的 Successfully built stem 表示 stem 以源码包形式现场构建——离线安装方案（第五章）必须把构建所需的 setuptools 一并带回，实测已在离线包清单中包含；
  • 末行 root 运行 pip 的 WARNING 是提示性告警，root 服务器上单机使用可忽略；生产多用户环境建议用 pip3 install --user 或虚拟环境。

4.4 验证安装

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

实测回显：

│                  v2.7.1                   │

onionshare-cli 没有独立的 --version 参数（实测 --version 会报 error: unrecognized arguments: --version），版本号打印在启动横幅中央，这是 2.7.1 的官方行为。

4.5 首次运行验证（不依赖 Tor 的最小闭环）

用 --local-only 参数做一次不接入 Tor 的本地启动，验证 Web 服务部分可用：

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 服务层是否正常」的利器：如果 local-only 能起服务而正常模式连不上 Tor，问题一定在 Tor 接入层（见第七章）。按 Ctrl+C 退出。

五、方案 B：离线 wheel 安装（断网服务器）

5.1 方案说明

目标服务器无法访问 PyPI 时，在一台同架构、同大版本 Python 的联网机器上用 pip3 download 把主包与全部依赖打包，拷贝到目标机后用 --no-index --find-links 离线安装。本节命令已在 Ubuntu 22.04 环境实测。

5.2 联网机：下载离线包

mkdir -p /root/offline-all
pip3 download onionshare-cli==2.7.1 -d /root/offline-all

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

Saved /root/offline-all/setuptools-84.2.1-py3-none-any.whl
Successfully downloaded onionshare-cli flask stem werkzeug cffi click cython flask-compress flask-socketio gevent packaging pkgconfig pynacl qrcode pysocks urllib3 waitress wheel colorama eventlet gevent-websocket psutil unidecode blinker certifi charset_normalizer dnspython greenlet idna itsdangerous jinja2 markupsafe python-socketio backports.zstd brotli pycparser pypng requests typing-extensions zope.event zope.interface bidict python-engineio simple-websocket wsproto h11 setuptools

打包核查：

ls /root/offline-all | wc -l
du -sh /root/offline-all

实测回显：

47
17M	/root/offline-all

47 个包共 17 MB。⚠️ 注意：清单里必须包含 setuptools（stem 在安装时现场构建需要它），pip3 download 默认已自动带入；若用 --no-deps 只下主包则离线装不上。

5.3 目标机：拷贝与离线安装

把 /root/offline-all/ 整个目录（scp/U 盘均可）拷到目标服务器后执行：

pip3 install --no-index --find-links=/root/offline-all onionshare-cli==2.7.1

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

Requirement already satisfied: h11<1,>=0.16.0 in /usr/local/lib/python3.10/dist-packages (from wsproto->simple-websocket>=0.10.0->python-engineio>=4.15.1->python-socketio>=5.12.0->flask-socketio<6.0,>=5.6->onionshare-cli==2.7.1) (0.16.0)
Installing collected packages: onionshare-cli
Successfully installed onionshare-cli-2.7.1

⚠️ 注意：--no-index 禁用一切在线源，仅从 --find-links 目录取包。pip 在构建 stem 时默认开启构建隔离、会尝试联网拉 setuptools——离线包里已含 setuptools wheel，实测可正常完成构建；若目标机 pip 版本过旧报构建错误，先升级目标机 pip 再重试。

5.4 验证

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

实测回显：

│                  v2.7.1                   │

六、方案对比与选择建议

维度方案 A：在线 pip方案 B：离线 wheel
是否需联网安装期需访问 Ubuntu 源 + PyPI目标机全程离线（仅准备机联网）
包体积在线拉取 47 个依赖17 MB 目录整包拷贝
版本一致性按 PyPI 当前解析，需 pin ==2.7.1准备机锁定，版本完全一致
适用场景常规可联网服务器内网隔离/无外网出口的生产区
升级方式pip3 install -U onionshare-cli重新 download + 整包替换

选择建议：能联网直接走方案 A（官方路径、依赖自动解析）；生产内网与合规隔离区走方案 B，且离线包与目标机的 Python 大版本（Ubuntu 22.04 为 3.10）必须一致，否则 wheel 兼容性不成立。

七、Tor 网络接入配置（运行期关键）

OnionShare CLI 只是「洋葱服务的管理面」，真正的匿名通路由 Tor 建立。Tor 接入有两条路径，实测行为差异极大，务必按本节顺序排查。

7.1 路径一：automatic 自动模式（默认，需可直连 Tor）

onionshare-cli 不带任何连接配置时走 automatic 模式：自动拉起一个 tor 子进程并引导建链。在能直连 Tor 网络的服务器上这是零配置路径：

onionshare-cli /root/hello.txt --public --connect-timeout 90

受限网络下的实测回显（本机无法直连 Tor，真实输出）：

Connecting to the Tor network: 14% - Handshaking with a relay
Taking too long to connect to Tor. Maybe you aren't connected to the Internet, or have an inaccurate system clock?

进度长期卡在个位数百分比到 14% 区间（Connecting to a relay / Handshaking with a relay），直到 --connect-timeout（默认 120 秒）耗尽报错退出。这是 Tor 直连被网络阻断的典型特征，不是程序故障——解法是给 Tor 配置代理或网桥后改走路径二。

7.2 路径二：连接系统 tor 服务（受限网络实测可行）

思路：让系统 Tor 服务经代理出网完成引导，onionshare-cli 通过控制端口连上这个已建链的 Tor，再注册 onion 服务。以下全部步骤实测通过。

第一步：编辑 /etc/tor/torrc

SocksPort 9050
ControlPort 127.0.0.1:9051
CookieAuthentication 0
Socks5Proxy 192.168.1.72:7897
DataDirectory /var/lib/tor

逐项说明：

配置项含义说明
SocksPort 9050SOCKS 代理监听口CLI 的会话流量从 tor 的该口出网
ControlPort 127.0.0.1:9051控制端口onionshare-cli 经此口创建/管理 onion 服务
CookieAuthentication 0关闭 Cookie 认证配合 CLI 配置里的 auth_type: no_auth；⚠️ 该组合下 tor 会在日志发安全警告（见下），生产建议改密码认证
Socks5Proxy 192.168.1.72:7897Tor 自身出网走的前置代理Tor 全部流量（含目录获取、建链）都经此前置代理；没有受限网络问题的服务器不要配此项
DataDirectory /var/lib/torTor 运行数据目录Ubuntu 包默认，属主为 debian-tor

第二步：校验配置语法

tor 配置文件改完先做语法校验（以 debian-tor 用户执行，原因见第九章 Q2）：

su -s /bin/bash debian-tor -c "tor --verify-config"

实测回显：

Configuration was valid

第三步：启动 Tor 服务并验证引导完成

systemd 服务器上用系统服务方式启动（服务默认以 debian-tor 用户运行，直接规避数据目录权限问题）：

systemctl restart tor     # 每行仅一个单元
systemctl is-active tor   # 预期输出 active

⚠️ 上述 systemctl 命令需要带 systemd 的 Linux 真机执行（Ubuntu 22.04 服务器默认满足）。引导进度验证（等 30–90 秒后执行）：

journalctl -u tor | grep "Bootstrapped 100"

预期输出形态：Bootstrapped 100% (done): Done。本文实测采用控制端口查询方式，回显如下：

python3 - <<'PY'
import socket
s = socket.create_connection(('127.0.0.1', 9051), 5)
s.sendall(b'AUTHENTICATE ""\r\nGETINFO status/bootstrap-phase\r\nQUIT\r\n')
import time; time.sleep(2)
print(s.recv(65536).decode())
PY

实测回显（Tor 完成引导后）：

250 OK
250-status/bootstrap-phase=NOTICE BOOTSTRAP PROGRESS=100 TAG=done SUMMARY="Done"
250 OK
250 closing connection

PROGRESS=100 TAG=done 即建链完成，onion 服务才可以注册。

第四步：写 onionshare-cli 全局配置

CLI 的默认配置文件路径为 ~/.config/onionshare/onionshare.json（Linux 下数据目录遵循 XDG 约定，实测该目录由 CLI 自动创建，persistent 会话默认也存放在其 persistent/ 子目录）。写入连接方式：

mkdir -p /root/.config/onionshare
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

字段含义：connection_type 取 control_port 表示「连一个已在运行的 Tor」；control_port_* 与 socks_* 指向 torrc 里开的两个端口；auth_type 与 torrc 的认证方式对应；bridge_use 为是否启用网桥。全部字段详解见本专栏 《OnionShare 2.7.1 配置参数详解》。

第五步：真实分享闭环验证

echo "OnionShare on Ubuntu 22.04" > /root/hello.txt
onionshare-cli /root/hello.txt --public

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

Preparing file.

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

Press Ctrl+C to stop the server

拿到 *.onion 地址即代表全链路打通：CLI → 控制端口 → Tor（经代理建链）→ onion 网络注册成功。对方用 Tor Browser 打开该地址即可下载（访客侧姿势见 《OnionShare 介绍与选型指南》第五章）。

八、systemd 托管（服务器常驻）

收件箱（Receive）等长期服务的官方建议是「专用常开设备」，用 systemd 托管是标准做法。⚠️ 本节命令需 systemd 真机执行。

Tor 服务：apt 安装的 tor 包自带 systemd 单元，前章已用 systemctl restart tor 启动；开机自启：

systemctl enable tor      # 每行仅一个单元

OnionShare 常驻服务单元：以常驻 Receive 收件箱为例，新建 /etc/systemd/system/onionshare-receive.service：

[Unit]
Description=OnionShare CLI Receive Mode
After=network-online.target tor.service
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/onionshare-cli --receive --public
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

说明：ExecStart 用 pip 脚本路径（root 安装在 /usr/local/bin/onionshare-cli，按实际 command -v onionshare-cli 输出修正）；--receive --public 语义见本专栏 《OnionShare 2.7.1 常用 CLI 命令详解》。启用：

systemctl daemon-reload      # 每行仅一个单元
systemctl enable onionshare-receive
systemctl start onionshare-receive
systemctl is-active onionshare-receive   # 预期输出 active

onion 地址与私钥在服务日志中查看：journalctl -u onionshare-receive | grep "Give this address"。若需要重启后地址不变，加 --persistent 参数并指定会话文件（机制与排障见命令篇第六章）。

九、常见问题（FAQ）

Q1：onionshare-cli 卡在 "Connecting to the Tor network: 5%/14%" 然后超时退出？ 实测回显见 7.1 节（Taking too long to connect to Tor. Maybe you aren't connected to the Internet...）。定位：Tor 无法直连建链（进度长期停在 Connecting to a relay / Handshaking with a relay）。解决：按 7.2 节给 tor 配 Socks5Proxy 前置代理或配置网桥（bridge_use 相关项），走控制端口路径。

Q2：手动以 root 跑 tor 报 Couldn't create private data directory "/var/lib/tor"？ 实测回显：

[warn] /var/lib/tor is not owned by this user (root, 0) but by debian-tor (101). Perhaps you are running Tor as the wrong user?
[warn] Failed to parse/validate config: Couldn't create private data directory "/var/lib/tor"
[err] Reading config failed--see warnings above.

定位：/var/lib/tor 属主是安装时创建的 debian-tor 用户，root 进程无权使用。解决：不要手动以 root 跑 tor，用系统服务（systemctl start tor，服务自动以 debian-tor 运行）；确需手动调试则 su -s /bin/bash debian-tor -c "tor -f /etc/tor/torrc"。

Q3：tor 报 Address already in use. Is Tor already running?？ 实测回显：

[warn] Could not bind to 127.0.0.1:9050: Address already in use. Is Tor already running?
[warn] Failed to parse/validate config: Failed to bind one of the listener ports.

定位：9050/9051 端口已被另一个 tor 实例占用（常见于旧实例未退、或 systemd 服务与手动进程并存）。解决：systemctl is-active tor 确认服务态，杀掉多余的手动 tor 进程后再启动，保证同时只有一个 tor 实例。

Q4：onionshare-cli 报 Can't connect to the Tor controller at 127.0.0.1:9052.？ 实测回显（把配置故意指向未监听的 9052 端口复现）：

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

定位：onionshare.json 里 control_port_port 与 tor 实际监听不一致，或 tor 未启动。解决：用 7.2 节的 GETINFO status/bootstrap-phase 探针确认控制端口与引导状态，再核对配置文件。

Q5：tor 日志出现 ControlPort is open, but no authentication method has been configured ... That's bad!？ 这是 CookieAuthentication 0 + 无密码组合下 tor 的安全警告（实测回显原文）。本机单用户环境风险可控；生产服务器建议改用 CookieAuthentication 1 或 HashedControlPassword 密码认证，并在 onionshare.json 里同步 auth_type 与 auth_password。

Q6：pip 装完找不到 onionshare-cli 命令？ pip 依安装方式把入口脚本放在 /usr/local/bin/ 或 ~/.local/bin/。用 command -v onionshare-cli 定位；~/.local/bin 不在 PATH 时把它追加进 PATH 或改用绝对路径调用。

十、卸载与清理

pip3 uninstall -y onionshare-cli   # 卸载 CLI 主包
apt-get remove --purge -y tor      # 卸载 Tor（含配置文件）

收尾核查与数据清理（收件目录与 CLI 数据目录在卸载后仍会保留）：

command -v onionshare-cli || echo "cli removed"
rm -rf /root/.config/onionshare /root/OnionShare

十一、参考链接