随时掌握你的设备状态

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

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

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

在设备安装 PiDOC

将以下命令复制到设备的bash窗口执行即可：

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

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

pidoc version

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

Pidoc Endpoint v2.0.12

安装特定版本

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

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

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

功能

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

带宽规则

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

提示

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

💬 免费 AI 对话（本地 API）

PiDOC 内置免费 AI 对话能力，在设备安装 v2.0.12+ 版本的客户端后（安装方法），设备会自动在本地启动一个 OpenAI 兼容 API，为 PicoClaw、OpenClaw 等应用提供 AI 能力。

本地 API 地址：http://127.0.0.1:11434/v1

PicoClaw / OpenClaw 配置

在应用的 LLM 设置中选择 OpenAI 兼容 API，填入以下信息：

配置项	填写内容
API Base URL	`http://127.0.0.1:11434/v1`
API Key	任意值（如 `pidoc`）
Model ID	`auto`

所有请求通过 SSH 隧道转发到 PiDOC 代理服务器，代理端调用云端大模型为您服务。

curl 测试

curl http://127.0.0.1:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "你好，请用一句话介绍自己"}]
  }'

支持的功能

对话补全：POST /v1/chat/completions
模型查询：GET /v1/models （返回模型 ID: auto）
流式与非流式响应
工具调用（Function Calling） — AI 编码助手（如 CodeBuddy / Cline）也可使用

使用须知

免费：该功能完全免费，无需额外付费
Token 随意填写：API Key 字段填写任意字符串即可，不验证
纯文本模型：仅支持文字对话，不支持图片等多模态输入
有限流保护：每分钟 10 次请求 / 50000 tokens，每小时 100 次 / 500000 tokens，每天 1000 次 / 2000000 tokens，超限后返回错误

备注

本地 API 在 PiDOC 客户端与服务器连接成功后自动启动，断开连接后自动停止。请确保客户端运行正常后再使用。

注意

该功能为公共资源，请合理使用。频繁触发限流说明您的客户端可能存在自动重试或过度调用的情况，请调整使用频率。

注册

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

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

接入新设备

复制命令行并在安装好Pidoc程序的设备上执行。

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

设备别名

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

提示

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

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

查看指标监控

指标监控提供的信息有：

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

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

网页远程访问

为了解决设备在内网环境中无法控制的问题，PiDoc工具开发了 远程访问 功能。在页面左侧导航栏中点击 远程访问 会打开一个页面新窗口。

远程访问支持下列功能：

SSH终端
SFTP文件
VNC桌面

SSH终端

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

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

SFTP文件

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

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

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

VNC桌面

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

请根据您设备的实际情况选择填写端口，如VNC端口可访问，则会弹出窗口提供输入 用户名与密码。如无法访问，请检查设备上的 VNC 服务是否已开启以及端口是否正确

堡垒SSH

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

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

创建堡垒密钥

在页面左侧导航栏中点击 密钥管理 会打开一个堡垒密钥的列表页面。你可以在此页面管理堡垒密钥。
如果您已经有常用的密钥对，则可以直接使用。
否则，您可以点击 创建密钥 按钮创建一个新的密钥对。该密钥对为 ED25519 类型。

重要

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

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

创建 SSH config 文件

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

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

Windows 命令行
Windows PowerShell

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

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 文件

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

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

SSH config文件示例：

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

# 代理跳转主机下配置
Host ops.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 '[ops.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
    # 指定代理跳转的主机配置项，这里我们使用 `ops.pidoc.cn`
    ProxyJump ops.pidoc.cn

# 代理跳转主机下配置
Host ops.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 连接、我的世界游戏连接等。该功能需要PidocDesktop 客户端支持。

下载：PidocDesktop Win64 V0.1.2

注意

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

客户端登录

生成 Token

登录 PidocDesktop

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

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

VNC 连接

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

设备的 VNC 端口默认为 5900，所以这里我们填入 5900。

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

转发规则运行中。

提示

现在就可以通过 VNC 客户端连接到您的设备了，地址为 localhost:5900。

SSH 连接

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

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

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

转发规则运行中。

提示

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

网站转发

如果您有OpenClaw、Home Assistant等需要通过网站访问的应用，则可以使用网站转发功能。

例如您访问 OpenClaw 的 WebUI，则可以通过网站转发功能将 OpenClaw 的 WebUI 转发到本地。

重要

网站转发功能登录ops.pidoc.cn，在登录有效期内才可正常访问。

配置文件

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

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

{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds="
}

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

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

{
  "private_key": "5woUnsa2BGl3CGWXy20ovB2dUXG95gKz2wZKBu0kdds=",
  "server_addr": "ops.pidoc.cn:3322",
  "websocket": true,
  "websocket_url": "wss://ops.pidoc.cn/api/endpoint/ws-tunnel",
  "forward_port_whitelist": [22, 5900],
  "client_id": "my-custom-client-id",
}

卸载

请使用如下命令：

sudo apt remove pidoc

故障排查

如果失败可以考虑检查：

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

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 隧道。检查：
# 查看是否有到 ops.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隧道架构的内网穿透和远程访问平台,包含:

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

三重加密保护

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

安全特性

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

为什么是安全的?

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

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

在设备安装 PiDOC​

安装特定版本​

功能​

带宽规则​

💬 免费 AI 对话（本地 API）​

PicoClaw / OpenClaw 配置​

curl 测试​

支持的功能​

使用须知​

注册​

接入新设备​

设备别名​

查看指标监控​

网页远程访问​

SSH终端​

SFTP文件​

VNC桌面​

堡垒SSH​

创建堡垒密钥​

创建 SSH config 文件​

配置 SSH config 文件​

SSH 登录设备​

多台设备的简化配置​

scp 传输文件​

VS Code 远程开发​

本地转发​

客户端登录​

生成 Token​

登录 PidocDesktop​

VNC 连接​

SSH 连接​

网站转发​

配置文件​

卸载​

故障排查​

兼容性​

安全性​

架构概览​

三重加密保护​

安全特性​

为什么是安全的?​