随时掌握你的设备状态

PiDoc 是由本站提供的树莓派（也兼容其他派）的一站式信息工具，其提供了设备指标监控。还可以通过本站公网堡垒机中转 ssh 的方式随时访问树莓派。适用于持续运行树莓派的用户或是使用树莓派的开发者。如您有一台或多台树莓派，通过PiDoc工具可很好的随时掌握其运行状态。

请到 Pidoc远程管理网站 注册一个账号，并按照指引接入新设备。

交流QQ群：498908352 (反馈问题、提供建议等)

功能

• 实时监控：CPU负载、网络、磁盘、温度 等监测
• 网页终端：在世界任何地方安全访问您的树莓派
• 堡垒SSH：提供双层防护，以SSH Proxy 的方式提供堡垒SSH
• 本地转发：将远程树莓派的端口映射到本地，实现 VNC连接、我的世界 游戏连接等

带宽规则

• 独享2Mbps：每个设备固定2Mbps基础带宽（独享）
• 共享100Mbps：100Mbps全局共享加速池（所有用户共享）
• 动态分配：根据实际使用情况动态调整带宽，极速能达 102Mbps
• 加速条件： 设备低带宽时积累加速流量，当有需要时消耗加速流量

提示

以上功能为提供给网友的便利措施，全免费。整体资源有限，请合理使用。

注册

去 Pidoc远程管理网站 注册一个账号。

注册需要邮箱，收到验证邮件点击内容中的"验证邮箱"或复制链接到浏览器中打开以验证邮箱。

在树莓派安装 PiDoc

将以下命令复制到树莓派的bash窗口执行即可：

curl -fsSL https://dl.pidoc.cn/remote/install.sh | bash

检查是否安装成功，可执行下面的命令：

pidoc version

如安装正常，则会显示出pidoc的版本号，例如：

Pidoc Endpoint v2.0.2

安装特定版本

可以指定版本号安装。如当前设备已安装PiDoc，则指定版本不能小于已安装版本。例如安装 v2.0.6 版本：

PIDOC_VERSION=2.0.6 bash <(curl -sSL https://dl.pidoc.cn/remote/install.sh)

各种版本及架构可在 这里 查看。

接入新设备

登录 Pidoc远程管理网站 ，在 设备管理 页面点击 增加 按钮。

复制命令行并在安装好Pidoc程序的树莓派上执行。

输出信息示例：

$ sudo pidoc service install 5woUns**********
2026/02/18 12:06:58 正在安装 Pidoc Endpoint 服务...
2026/02/18 12:06:58 ✓ 创建配置目录: /etc/pidoc
2026/02/18 12:06:58 ✓ 保存配置文件: /etc/pidoc/config.json
2026/02/18 12:06:58 ✓ 创建服务文件: /etc/systemd/system/pidoc.service
2026/02/18 12:06:58 ✓ 重新加载 systemd
2026/02/18 12:06:58 ✓ 启用服务: pidoc
2026/02/18 12:06:58 ✓ 重启服务: pidoc
2026/02/18 12:06:58 
========================================
2026/02/18 12:06:58 服务安装成功！
2026/02/18 12:06:58 配置文件: /etc/pidoc/config.json
2026/02/18 12:06:58 服务名称: pidoc
2026/02/18 12:06:58 
常用命令:
2026/02/18 12:06:58   查看状态: systemctl status pidoc
2026/02/18 12:06:58   查看日志: journalctl -u pidoc -f
2026/02/18 12:06:58   停止服务: systemctl stop pidoc
2026/02/18 12:06:58   启动服务: systemctl start pidoc
2026/02/18 12:06:58   重启服务: systemctl restart pidoc
2026/02/18 12:06:58 ========================================

如果一切正常，您将会在 设备管理 页面看到新接入的设备。

设备别名

每台新设备加入时，会使用设备类型及序列号自动生成一个设备别名。树莓派的前缀为 rpi-，香橙派的前缀为 opi-。 如果设备的序列号为 123456789 ，则设备会显示为 rpi-123456789 或 香橙派 的 opi-123456789。

提示

设备别名可以更改，点击设备名称旁的铅笔图标即可修改。建议将其修改为便于自己识别的名称。

修改后的设备别名必须具有唯一性，因为在进行跳转时会使用别名寻找对应设备。

查看指标监控

指标监控提供的信息有：

• 系统：运行时间
• CPU：负载、温度
• 内存：使用率
• 磁盘：使用率

如有多台设备，可以在左上方选择对应设备，还可以在右侧选择时间范围查看指标监控。

更多指标已上报待展示，敬请期待。

网页SSH终端

为了解决树莓派在内网环境中无法控制的问题，PiDoc工具开发了 网页SSH 功能。在页面左侧导航栏中点击 SSH连接 会打开一个网页SSH页面新窗口。

点击Tab + 号或页面中间的 新建连接 ，然后选择 SSH终端。

请根据您设备的实际情况选择填写 用户名、端口，选择 密码认证 或 私钥认证。

网页SFTP文件

为了解决树莓派在内网环境中无法控制的问题，PiDoc工具开发了 网页SFTP 功能。在页面左侧导航栏中点击 SSH连接 会打开一个网页SSH页面新窗口。

点击Tab + 号或页面中间的 新建连接 ，然后选择 SFTP文件。

请根据您设备的实际情况选择填写 用户名、端口，选择 密码认证 或 私钥认证。

连接成功后将看到服务器的文件列表。你可以切换目录、支持文件多选、支持文件拖放上传、支持文件下载。

堡垒SSH

如果您想使用 SSH 的 scp 传输文件，或是想通过 VSCode等等 IDE远程访问树莓派，可以使用 堡垒SSH 功能。

堡垒SSH 本质上是一个 SSH 代理，它会将您的请求转发到树莓派上。对于该功能的使用需要您有一定的SSH配置知识。

创建堡垒密钥

1. 在页面左侧导航栏中点击 密钥管理 会打开一个堡垒密钥的列表页面。你可以在此页面管理堡垒密钥。

   

2. 如果您已经有常用的密钥对，则可以直接使用。

   

3. 否则，您可以点击 创建密钥 按钮创建一个新的密钥对。该密钥对为 ED25519 类型。

   

重要

请妥善保管您的 私钥，不要泄露给他人。下载窗口关闭后将无法再次获取，请确保您已经下载好私钥。

建议将私钥文件放置到 %USERPROFILE%\.ssh\ 目录。

创建 SSH config 文件

SSH config 文件是 SSH 客户端的配置文件，用于存储 SSH 连接的配置信息。在 Windows 上，SSH config 文件位于 %USERPROFILE%\.ssh\config。

下面的命令会在当前用户下检查 .ssh 是否已经存在，如不存在则创建一个。随后并打开或创建一个 SSH config 文件。

Windows 命令行

(if not exist "%USERPROFILE%\.ssh" mkdir "%USERPROFILE%\.ssh") & notepad "%USERPROFILE%\.ssh\config"

Windows PowerShell

if (-not (Test-Path "$env:USERPROFILE\.ssh")) { New-Item -Path "$env:USERPROFILE\.ssh" -ItemType Directory -Force | Out-Null }; notepad "$env:USERPROFILE\.ssh\config"

配置 SSH config 文件

堡垒机基本信息。地址 remote.pidoc.cn，端口 64422，用户名任意。

目标设备使用主机别名进行连接（设备管理中的第一列，别名可以更改），端口请指定为 OpenSSH 的服务端口，一般为 22。

SSH config文件示例：

# 堡垒使用主机别名进行连接（设备管理中的第一列，别名可以更改），这里我们使用 `rpi-5`。
Host rpi-5
    # 树莓派SSH用户名，请根据您的实际情况修改
    User pi
    # 树莓派SSH端口，请根据您的实际情况修改
    Port 22
    # 树莓派的私钥文件路径
    IdentityFile ~/.ssh/id_rsa
    # 指定代理跳转的主机配置项，这里我们使用 `remote.pidoc.cn`
    ProxyJump remote.pidoc.cn

# 代理跳转主机下配置
Host remote.pidoc.cn
    # 代理主机端口，这里我们使用 `64422`。
    Port 64422
    # 堡垒机的私钥文件路径，请改为您的实际情况
    IdentityFile ~/.ssh/id_ed25519_bastion

SSH 登录树莓派

# SSH登录树莓派，这里我们使用 `rpi-5`作为示例。
ssh rpi-5

第一次登录可能会出现下面的提示信息，请输入 yes。

PS C:\Users\testuser\.ssh> ssh rpi-5
The authenticity of host '[remote.pidoc.cn]:64422 ([101.43.71.125]:64422)' can't be established.
ED25519 key fingerprint is SHA256:cpqRJXY7CJxrq1yxkU5MOBNKG9TKhsJlH6QduB7uetY.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

如果登录成功，则会显示树莓派的欢迎信息。

如果登录失败，请检查 SSH config 文件是否正确配置。

如果无法确认问题在哪里，请使用下面命令进行调试。

# 使用-v参数可以显示详细信息，这里我们使用 `rpi-5`作为示例。
ssh -v rpi-5

多台设备的简化配置

如果您有多台树莓派，则可使用 SSH Config 通配机制，这样是无须为每一台设备指定登录信息，除非该设备需要特殊配置。

# 堡垒使用主机别名进行连接，使用*号可通配。
Host rpi-*
    # 树莓派SSH用户名，请根据您的实际情况修改
    User pi
    # 树莓派SSH端口，请根据您的实际情况修改
    Port 22
    # 树莓派的私钥文件路径
    IdentityFile ~/.ssh/id_rsa
    # 指定代理跳转的主机配置项，这里我们使用 `remote.pidoc.cn`
    ProxyJump remote.pidoc.cn

# 代理跳转主机下配置
Host remote.pidoc.cn
    # 代理主机端口，这里我们使用 `64422`。
    Port 64422
    # 堡垒机的私钥文件路径
    IdentityFile ~/.ssh/id_rsa_bastion

scp 传输文件

# scp 传输文件，这里我们使用 `rpi-5`作为示例。

# 从本地传输文件到远程树莓派
scp ./localfile.txt rpi-5:/home/pi/

# 从远程树莓派传输文件到本地
scp rpi-5:/home/pi/remotefile.txt ./

VS Code 远程开发

VSCode 远程开发需要安装 Remote SSH 插件。

插件安装完成后，从左侧导航栏中点击 Remote-SSH 插件图标。在远程资源管理器中 远程(隧道/SSH) 选择您的设备，点击右箭头以VS Code 远程模式打开新窗口。

本地转发

本地转发功能可以将远程树莓派的端口映射到本地，实现 VNC 连接、我的世界 游戏连接等。该功能需要PidocAgent 客户端支持。

下载：PidocAgent Win64 V0.1.0

注意

PidocAgent 在Beta阶段，如遇问题请入群反馈。

客户端登录

登录 Agent 需要在 Pidoc远程管理网站 中生成 Agent Token。然后将 Token 填写到 Pidoc Agent 客户端的登录信息中。

生成 Token

登录 Agent

在 Windows 中打开 Pidoc Agent 客户端，填入 Token 登录。

登录成功后将显示设备列表。

VNC 连接

在端口转发功能中添加新的转发规则。

树莓派的 VNC 端口默认为 5900，所以这里我们填入 5900。

点击 右箭头，运行转发规则。

转发规则运行中。

提示

现在就可以通过 VNC 客户端连接到树莓派了，地址为 localhost:5900。

SSH 连接

在端口转发功能中添加新的转发规则。

由于 SSH 端口的编号较小，在某些情况下本地可能已被占用或是没有权限，所以这里我们源端口填入 60022 以避免冲突。 树莓派的 SSH 端口默认为 22，所以这里我们目标端口填入 22。

点击 右箭头，运行转发规则。

转发规则运行中。

提示

现在就可以通过 SSH 客户端连接到树莓派了，地址为 localhost:22。

github稳定访问

在某些网络环境中，访问 github.com 可能存在稳定性差、速度慢等问题。其中一个原因是163骨干网由境外回程极为拥堵，造成使用体验不佳。

PiDoc 2.0.9 版本开始支持 github 访问线路优化。本站租用了 CN2 GIA 商业线路，提升访问 github 回程的稳定性，实测速度约为稳定的 1.1MB/s。

编辑配置文件 /etc/pidoc/config.json，启用配置项

{
  "private_key": "你设备的密钥，无须更改",
  "http_proxy_enabled": true,  // 启用 HTTP 代理
  "http_proxy_listen": "localhost:38090", // HTTP 代理监听地址
  "http_proxy_domains": ["*.github.com", "*.githubusercontent.com"]  // HTTP 代理域名白名单。该配置为本地逻辑分支，确定是否直连。实际白名单仍由后端控制。
}

然后，重启服务

sudo systemctl restart pidoc

使用如下命令测试是否能否能稳定访问 github

https_proxy=http://localhost:38090 curl https://github.com

如能看到输出HTML，则表示可以稳定访问 github。

配置 git 程序使用代理，且只对 github.com 和 githubusercontent.com 域名生效。

git config --global http.https://github.com.proxy http://localhost:38090
git config --global http.https://githubusercontent.com.proxy http://localhost:38090

注意

1. 未使用VPN等技术，您的访问源/目等元组信息仍置于监管规则之下。（它不是 “翻墙” 或 “科学上网”）
2. 如您所在运营商阻塞了目标地址，则使用该功能也无法访问目标地址。它只提升稳定性，不提升穿越能力。
3. 如您无须设置即可稳定访问 github，则不要启用该项功能。带宽为商业付费，有一定成本。
4. 请尽量不要设置为系统级的代理，避免在pidoc程序未运行时影响当前设备访问网络。

配置文件

PiDoc 配置文件位于 /etc/pidoc/config.json，该文件在执行 pidoc service install 时自动生成。

标准安装后的配置文件仅有一个密钥字段，示例如下：

{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds="
}

PiDoc的增强功能需要手工编辑配置文件开启，完整的字段及功能描述如下。

字段名	类型	描述	支持的版本
private_key	string	私钥，用于加密通信。该密钥在管理界面的 设备管理--增加 中生成。	2.0.0
server_addr	string	堡垒机服务器地址。当前仅有 remote.pidoc.cn:3322 可用，可不填写。未来会提供更多服务器地址以分担压力。	2.0.7
websocket	boolean	是否启用 WebSocket。在一些网络环境中，需要启用 WebSocket 穿越防火墙。	2.0.6
websocket_url	string	WebSocket 地址穿越服务URL。当前仅有 wss://remote.pidoc.cn/api/endpoint/ws-tunnel 可用，可不填写。未来会提供更多服务器地址以分担压力。	2.0.7
forward_port_whitelist	array of int	端口转发白名单，用于限制端口转发的范围以提升安全性。	2.0.7
client_id	string	自定义客户端ID（可选，为空则自动获取设备序列号）。同一账号下的多个设备的客户端ID不能相同	2.0.8
http_proxy_enabled	boolean	是否启用 HTTP 代理	2.0.9
http_proxy_listen	string	HTTP 代理监听地址（默认 localhost:38090）	2.0.9
http_proxy_domains	array of string	HTTP 代理允许的域名列表，白名单由服务端控制，本地只做为备份措施。不在列表中的域名由pidoc本地转发。	2.0.9

{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds=",
  "server_addr": "remote.pidoc.cn:3322",
  "websocket": true,
  "websocket_url": "wss://remote.pidoc.cn/api/endpoint/ws-tunnel",
  "forward_port_whitelist": [22, 5900],
  "client_id": "my-custom-client-id",
  "http_proxy_enabled": true,
  "http_proxy_listen": "localhost:38090",
  "http_proxy_domains": ["*.github.com", "*.githubusercontent.com"]
}

卸载

请使用如下命令：

sudo apt remove pidoc

故障排查

如果失败可以考虑检查：

1. 树莓派 SSH 服务未启动或端口不对
2. 登录 https://remote.pidoc.cn 检查：设备是否显示在线（绿色状态）？
3. 点击设备查看详情，确认 SSH 端口确实是 22？
4. 树莓派上的 sshd 服务是否运行？
5. 在树莓派本地执行：

sudo systemctl status ssh
sudo netstat -tlnp | grep 22

如果还是卡住，检查树莓派上的 pidoc 客户端（堡垒机代理）是否正常运行：

# 在树莓派上执行
sudo systemctl status pidoc    # 或类似名称的服务
ps aux | grep -i pidoc
ps aux | grep -i remote
#pidoc.cn 的客户端通常是一个反向 SSH 隧道。检查：
# 查看是否有到 remote.pidoc.cn 的连接
sudo netstat -tnp | grep 64422
sudo ss -tnp | grep pidoc
sudo systemctl restart pidoc

兼容性

Pidoc 支持的设备类型及操作系统包括但不限于：

设备	Debian 12	Debian 13	Ubuntu 22	Ubuntu 24	Armbian 25
Raspberry Pi 5	✅	✅	❌	✅	✅
Raspberry Pi 4	✅	✅	✅	✅	✅
Raspberry Pi 3	✅	✅	✅	✅	✅
Orange Pi CM4	-	-	✅	-	✅
Alientek QuarkPI-CA2	✅	-	-	-	-
NanoPi R4S	-	-	-	-	✅
Arduino UNO Q	-	✅	-	-	-

支持的设操作系统包括但不限于：Raspberry Pi OS、Debian、Ubuntu、Armbian、Kali Linux、Linux Mint、银河麒麟 Kylin、统信 UOS、深度 Deepin、麒麟信安 OS 等。

支持的芯片架构：arm64、armhf、amd64、i386、riscv64、loong64 等。

说明

• 通过兼容性验证的设备和操作系统均为实际测试通过的版本。你手头的设备或操作系统可能与此列表不同，但只要满足兼容性要求，也应该能够正常工作。
• Ubuntu 22.04: 不支持树莓派5，因 Ubuntu 从 23.10 起才开始支持树莓派5
• Armbian: 适用于香橙派等开发板，基于 Debian/Ubuntu
• ✅ 支持 | ❌ 不支持 | - 未测试或不适用

安全性

架构概览

Pidoc 及其组件是一个三层SSH隧道架构的内网穿透和远程访问平台,包含:

1. Pidoc(客户端) - 安装在您的设备上
2. Pidoc Proxy(跳板服务器) - 部署在公网的中转服务器
3. 用户SSH终端 - 您用来访问设备的工具(SSH客户端、浏览器WebSSH 或 Pidoc Agent)

三重加密保护

• 第一层：Pidoc ↔ Proxy (Ed25519公钥认证 + SSH加密)
• 第二层：用户 ↔ Proxy (多种认证 + SSH加密)
• 第三层：Proxy ↔ 目标SSH服务 (透明转发)

安全特性

• ✅ 端到端SSH加密 - 所有数据在SSH协议层加密传输
• ✅ 公钥认证 - 密码永不通过网络传输
• ✅ 密钥绑定 - 每个设备使用唯一密钥，无法冒充
• ✅ 双重加密(Web模式) - TLS + SSH协议栈
• ✅ 用户隔离 - 每个用户只能访问自己的设备

为什么是安全的?

• 无单点解密风险 - Proxy只负责路由,不能解密用户SSH会话
• 零信任架构 - 每一层都需要独立认证和加密
• 私钥不出设备 - 私钥永远留在Endpoint本地
• 标准协议 - 基于OpenSSH，经过长期安全验证

---

中文翻译版以英文版相同知识授权方式共享：CC-BY-SA 4.0。