PanoOn Linux 文档 0.2.9

PANOON 0.2.9 · LINUX X86_64

Linux 安装与使用

发布包包含全屏入口、自动化 CLI、Worker 和控制器运行文件；不依赖桌面图形库。

下载 Linux 包 ↓ SHA-256 构建清单

系统要求

运行下载、TUI 与 Worker

Linux x86_64、glibc 2.30 或更高版本、Python 3（含 curses）、tmux、curl。

另外运行控制器

Node.js 24 或更高版本。独立下载不需要 Node.js。

uname -m
ldd --version | head -n 1
python3 --version
tmux -V

下载与校验

安装前必须验证 SHA-256。以下命令不会访问代码仓库。

curl -fLO https://app.rjfan.org/panoon/downloads/panoon-0.2.9-linux-x86_64.tar.gz
curl -fLO https://app.rjfan.org/panoon/downloads/panoon-0.2.9-linux-x86_64.tar.gz.sha256
sha256sum -c panoon-0.2.9-linux-x86_64.tar.gz.sha256

正确结果应为 panoon-0.2.9-linux-x86_64.tar.gz: OK。

个人安装

没有 sudo 权限时安装到当前用户目录，不影响其他用户。

PANOON_VERSION=0.2.9
PANOON_ROOT="$HOME/.local/opt/panoon/$PANOON_VERSION"
mkdir -p "$PANOON_ROOT" "$HOME/.local/bin"
tar -xzf panoon-0.2.9-linux-x86_64.tar.gz -C "$PANOON_ROOT"
ln -sfn "$PANOON_ROOT/panoon" "$HOME/.local/bin/panoon"
ln -sfn "$PANOON_ROOT/panoon-tui" "$HOME/.local/bin/panoon-tui"
ln -sfn "$PANOON_ROOT/panoon-worker" "$HOME/.local/bin/panoon-worker"
export PATH="$HOME/.local/bin:$PATH"

把最后一行加入自己的 Shell 配置后，新终端也能找到命令。

全局安装

管理员可安装到版本化目录，再用原子符号链接让所有用户调用同一版本。

sudo install -d -m 0755 /opt/panoon/releases/0.2.9
sudo tar -xzf panoon-0.2.9-linux-x86_64.tar.gz \
  -C /opt/panoon/releases/0.2.9
sudo ln -sfn /opt/panoon/releases/0.2.9 /opt/panoon/current
sudo ln -sfn /opt/panoon/current/panoon /usr/local/bin/panoon
sudo ln -sfn /opt/panoon/current/panoon-tui /usr/local/bin/panoon-tui
sudo ln -sfn /opt/panoon/current/panoon-worker /usr/local/bin/panoon-worker

不要把安装目录设为全员可写。每位用户的偏好保存在自己的 ~/.config/panoon/。

快速开始

panoon --self-test
panoon-tui --version
panoon-worker --version
panoon

panoon 打开全屏终端界面，记住当前用户填写的代理端口、输入和输出路径。脚本与精确参数使用 panoon-tui。

代理端口

真实下载和真实 Worker 都要求当前机器上的 HTTP/mixed 代理端口。端口属于运行命令的用户，不能假设整台服务器共用一个端口。

read -r -p 'PanoOn proxy port: ' PANOON_PROXY_PORT
curl --proxy "http://127.0.0.1:$PANOON_PROXY_PORT" \
  --connect-timeout 10 -fsS -o /dev/null \
  https://www.google.com/generate_204

PanoOn 会在下载或注册 Worker 前再执行 Google 连通性与真实街景瓦片预检。预检失败时不会开始任务。

为什么裸地址可能返回 403？

直接请求不带完整参数的瓦片端点并不是有效下载测试。PanoOn 使用完整的 zoom-0 瓦片请求、下载器请求头和图像解码验证。

独立下载

这是最简单的 Linux 工作流，不需要控制器或 Worker。

panoon-tui parse --input ./panoids.txt

panoon-tui download \
  --input ./panoids.txt \
  --output ./panoramas \
  --zoom 3 \
  --resize 2048x1024 \
  --workers 8 \
  --proxy-port "$PANOON_PROXY_PORT" \
  --jpeg-quality 95

输入支持 TXT、CSV、JSON 和 --inline。默认不覆盖已有结果：匹配 panoid 与 zoom 的现有 JPEG 会被跳过。

中断后继续

panoon-tui download \
  --input ./panoids.txt \
  --output ./panoramas \
  --zoom 3 --resize 2048x1024 --workers 8 \
  --proxy-port "$PANOON_PROXY_PORT" \
  --jpeg-quality 95 --resume

只重试失败项

panoon-tui download \
  --output ./panoramas \
  --zoom 3 --resize 2048x1024 --workers 4 \
  --proxy-port "$PANOON_PROXY_PORT" \
  --retry-failed

只有确实要重新下载已有图像时才添加 --overwrite。

全屏 TUI

直接运行 panoon。配置按当前 Linux 用户保存，退出页面不会停止后台 tmux Worker。

按键作用
N新建下载并按需启动当前用户的后台 Worker
W把当前机器作为现有控制器的工作节点
C复制供桌面 GUI 使用的连接字符串
P验证并更新控制器配对码
L查看当前用户 Worker 日志
S停止 Worker；停止后同一按键用于续跑
R刷新任务与节点状态
Q / Esc退出界面，后台任务继续

启动控制器

仅当你需要 Area 或分布式 Worker 时才需要控制器。下面示例假设发布包位于 $PANOON_ROOT，并要求 Node.js 24+。

read -r -s -p 'Pairing code: ' PANOON_PAIRING_CODE
echo
panoon-worker controller \
  --port 8787 \
  --pairing-code "$PANOON_PAIRING_CODE" \
  --node node \
  --service-script "$PANOON_ROOT/service-runtime/server.js"

长时间运行可放入 tmux。控制器拥有最终输出目录的写权限；不要启动多个控制器争用同一端口。

panoon-tui --server http://127.0.0.1:8787 status
安全提示

只把控制器端口开放给受信网络；配对码只发给获授权用户，不要写入公开脚本或文档。

连接 Worker 节点

Worker 必须使用自己机器上的代理端口，并在注册前自动预检。

read -r -p 'PanoOn proxy port: ' PANOON_PROXY_PORT
read -r -s -p 'Pairing code: ' PANOON_PAIRING_CODE
echo

panoon-worker run \
  --server http://CONTROLLER_HOST:8787 \
  --pairing-code "$PANOON_PAIRING_CODE" \
  --name "Linux Worker" \
  --workers 8 \
  --real \
  --proxy-port "$PANOON_PROXY_PORT" \
  --temp-dir "$HOME/.cache/panoon/worker"

--real 与 --proxy-port 缺一不可。最终文件由 Worker 上传回控制器写入，--temp-dir 只是本地缓存。

创建与查看任务

panoon-tui --server http://CONTROLLER_HOST:8787 workers list
panoon-tui --server http://CONTROLLER_HOST:8787 workers job create \
  --input ./panoids.txt \
  --output /path/on/controller/panoramas \
  --zoom 3 --resize 2048x1024 --jpeg-quality 95
panoon-tui --server http://CONTROLLER_HOST:8787 workers job poll JOB_ID

Area PanoID

Area 由控制器执行。边界至少包含三个 lat,lng 点，并用分号分隔。

panoon-tui --server http://127.0.0.1:8787 area strategy list
panoon-tui --server http://127.0.0.1:8787 area start \
  --bounds "-37.81,144.96;-37.80,144.97;-37.81,144.98" \
  --strategy hybrid --density sparse
panoon-tui --server http://127.0.0.1:8787 area poll JOB_ID
panoon-tui --server http://127.0.0.1:8787 area result JOB_ID \
  --output ./area-result

也可使用桌面端 Area PanoID 地图绘制多边形。Area 结果中的 TXT、CSV 或 JSON 可直接交给独立下载。

验证与排障

command -v panoon panoon-tui panoon-worker
panoon --self-test
panoon-tui --version
panoon-worker --version
panoon-tui config show

command not found

个人安装执行 export PATH="$HOME/.local/bin:$PATH"；全局安装检查 /usr/local/bin 是否在 PATH。

invalid_pairing_code

代理预检通过只说明网络可用。403 和该错误表示控制器拒绝了配对码；向控制器管理员获取当前授权码后重新连接。

停止后看不到续跑

重新运行 panoon，主界面的 S 会显示为“续跑 Worker”，并复用上次控制器、代理端口和并发设置。

已有结果仍被下载

不要使用 --overwrite；确认文件名仍包含匹配的 panoid 与 zoom。分布式任务会在创建前递归扫描控制器输出目录。

升级与卸载

升级时先下载并校验新包，解压到新的版本目录，再原子切换 current。保留旧目录即可快速回滚。

sudo ln -sfn /opt/panoon/releases/NEW_VERSION /opt/panoon/current
panoon --self-test
panoon-tui --version
panoon-worker --version

个人安装卸载时删除自己的三个符号链接和对应版本目录。只有在确定不再需要个人偏好与历史时，才删除 ~/.config/panoon。