@ystemsrx/cfshare 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +339 -336
- package/README.zh.md +339 -336
- package/dist/src/cli.js +12 -7
- package/package.json +1 -1
- package/src/cli.ts +14 -7
package/README.zh.md
CHANGED
|
@@ -1,168 +1,168 @@
|
|
|
1
|
-
<h1 align="center">☁️ CFShare</h1>
|
|
2
|
-
|
|
3
|
-
<p align="center">
|
|
4
|
-
通过 Cloudflare 隧道安全地将本地文件与服务分享到公网
|
|
5
|
-
</p>
|
|
6
|
-
|
|
7
|
-
<p align="center">
|
|
8
|
-
<img src="https://img.shields.io/badge/平台-macOS_|_Linux_|_Windows_(WSL2)-9cf?style=flat-square" alt="平台">
|
|
9
|
-
<img src="https://img.shields.io/badge/Node-≥22-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node">
|
|
10
|
-
<img src="https://img.shields.io/badge/OpenClaw-≥2026.1.29-E86D37?style=flat-square" alt="OpenClaw">
|
|
11
|
-
<img src="https://img.shields.io/badge/许可-MIT-97CA00?style=flat-square" alt="MIT">
|
|
12
|
-
</p>
|
|
13
|
-
|
|
14
|
-
<p align="center">
|
|
15
|
-
<strong>简体中文</strong>
|
|
16
|
-
|
|
|
17
|
-
<a href="./README.md">English</a>
|
|
18
|
-
</p>
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
## 📖 这是什么？
|
|
23
|
-
|
|
24
|
-
**CFShare** 是 [OpenClaw](https://github.com/openclaw/openclaw) 的社区插件，让你的 AI 助手能够：
|
|
25
|
-
|
|
26
|
-
- 🔗 **一键将本地端口**暴露为临时公网 HTTPS 链接（`https://*.trycloudflare.com`）
|
|
27
|
-
- 📁 **分享文件/目录**——自动起本地静态服务器 + 隧道，对方打开链接即可浏览/下载/预览（支持加密）
|
|
28
|
-
- 🔒 **内置安全策略**——Token/Basic 认证、速率限制、端口黑名单、排除规则
|
|
29
|
-
- ⏱️ **自动过期清理**——TTL 到期自动关闭隧道并删除临时文件
|
|
30
|
-
|
|
31
|
-
> [!NOTE]
|
|
32
|
-
> **无需 Cloudflare 账号**。CFShare 使用的是 [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)（`trycloudflare.com`），完全免费、即开即用。
|
|
33
|
-
|
|
34
|
-
---
|
|
35
|
-
|
|
36
|
-
## 🏗️ 工作原理
|
|
37
|
-
|
|
38
|
-
```mermaid
|
|
39
|
-
flowchart LR
|
|
40
|
-
subgraph LOCAL["你的电脑"]
|
|
41
|
-
A["本地服务 / 文件"]
|
|
42
|
-
B["[可选] 反向代理<br/>(认证 + 限流)"]
|
|
43
|
-
C["cloudflared tunnel"]
|
|
44
|
-
|
|
45
|
-
A --> B
|
|
46
|
-
B --> C
|
|
47
|
-
end
|
|
48
|
-
|
|
49
|
-
C ==>|Cloudflare Quick Tunnel| D["https://xxx.trycloudflare.com"]
|
|
50
|
-
E["对方浏览器"] --> D
|
|
51
|
-
```
|
|
52
|
-
|
|
53
|
-
CFShare 在内部完成：路径校验 → 文件复制到临时目录 → 启动只读静态服务器 → 挂载认证/限流反代 → 开启 `cloudflared` 隧道 → 设置过期回收。你只需告诉 AI “我要分享什么”，它会帮你完成剩下的工作。
|
|
54
|
-
|
|
55
|
-
---
|
|
56
|
-
|
|
57
|
-
## 🚀 安装步骤
|
|
58
|
-
|
|
59
|
-
### 第一步：确保已安装 OpenClaw
|
|
60
|
-
|
|
61
|
-
如果你还没有安装 OpenClaw，请先完成安装：
|
|
62
|
-
|
|
63
|
-
```bash
|
|
64
|
-
# 安装 OpenClaw（需要 Node.js ≥ 22）
|
|
65
|
-
npm install -g openclaw@latest
|
|
66
|
-
|
|
67
|
-
# 运行初始化向导
|
|
68
|
-
openclaw onboard --install-daemon
|
|
69
|
-
```
|
|
70
|
-
|
|
71
|
-
> [!TIP]
|
|
72
|
-
> 如果你不确定 Node.js 版本，运行 `node -v` 检查。推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理版本。
|
|
73
|
-
|
|
74
|
-
---
|
|
75
|
-
|
|
76
|
-
### 第二步：安装 `cloudflared`
|
|
77
|
-
|
|
78
|
-
CFShare 依赖 Cloudflare 的 `cloudflared` 命令行工具来创建隧道。
|
|
79
|
-
|
|
80
|
-
<details>
|
|
81
|
-
<summary><b>🍎 macOS</b></summary>
|
|
82
|
-
|
|
83
|
-
```bash
|
|
84
|
-
brew install cloudflare/cloudflare/cloudflared
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
</details>
|
|
88
|
-
|
|
89
|
-
<details>
|
|
90
|
-
<summary><b>🐧 Linux（Debian / Ubuntu）</b></summary>
|
|
91
|
-
|
|
92
|
-
```bash
|
|
93
|
-
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
|
|
94
|
-
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
|
|
95
|
-
sudo apt-get update && sudo apt-get install cloudflared
|
|
96
|
-
```
|
|
97
|
-
|
|
98
|
-
</details>
|
|
99
|
-
|
|
100
|
-
<details>
|
|
101
|
-
<summary><b>🪟 Windows（WSL2 内操作）</b></summary>
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
# 在 WSL2 中：
|
|
105
|
-
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
|
|
106
|
-
chmod +x /usr/local/bin/cloudflared
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
或在 Windows 原生 PowerShell / CMD 中使用 winget：
|
|
110
|
-
|
|
111
|
-
```powershell
|
|
112
|
-
winget install --id Cloudflare.cloudflared
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
</details>
|
|
116
|
-
|
|
117
|
-
**或者直接告诉 Agent 让他帮你安装**
|
|
118
|
-
|
|
119
|
-
安装后验证：
|
|
120
|
-
|
|
121
|
-
```bash
|
|
122
|
-
cloudflared --version
|
|
123
|
-
# 输出类似: cloudflared version 2025.x.x
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
> [!IMPORTANT]
|
|
127
|
-
> 只需安装 `cloudflared`，**不需要**运行 `cloudflared tunnel login`。Quick Tunnel 无需账号认证。
|
|
128
|
-
|
|
129
|
-
---
|
|
130
|
-
|
|
131
|
-
### 第三步：安装 CFShare 插件
|
|
132
|
-
|
|
133
|
-
**方式 A — 从 npm 安装（推荐）：**
|
|
134
|
-
|
|
135
|
-
```bash
|
|
136
|
-
openclaw plugins install @ystemsrx/cfshare
|
|
137
|
-
# 安装完成后，重启 Gateway：
|
|
138
|
-
openclaw gateway restart
|
|
139
|
-
```
|
|
140
|
-
|
|
141
|
-
**方式 B — 从本地目录安装（适用于开发）：**
|
|
142
|
-
|
|
143
|
-
如果你已经克隆了仓库：
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
# 先安装依赖
|
|
147
|
-
cd /path/to/cfshare
|
|
148
|
-
npm install
|
|
149
|
-
|
|
150
|
-
# 链接到 OpenClaw（开发模式，不复制文件）
|
|
151
|
-
openclaw plugins install -l .
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
---
|
|
155
|
-
|
|
156
|
-
### 第四步：启用插件并重启 Gateway
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
# 启用插件
|
|
160
|
-
openclaw plugins enable cfshare
|
|
161
|
-
|
|
162
|
-
# 重启 Gateway 使插件生效
|
|
163
|
-
openclaw gateway restart
|
|
164
|
-
```
|
|
165
|
-
|
|
1
|
+
<h1 align="center">☁️ CFShare</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
通过 Cloudflare 隧道安全地将本地文件与服务分享到公网
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="https://img.shields.io/badge/平台-macOS_|_Linux_|_Windows_(WSL2)-9cf?style=flat-square" alt="平台">
|
|
9
|
+
<img src="https://img.shields.io/badge/Node-≥22-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node">
|
|
10
|
+
<img src="https://img.shields.io/badge/OpenClaw-≥2026.1.29-E86D37?style=flat-square" alt="OpenClaw">
|
|
11
|
+
<img src="https://img.shields.io/badge/许可-MIT-97CA00?style=flat-square" alt="MIT">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<strong>简体中文</strong>
|
|
16
|
+
|
|
|
17
|
+
<a href="./README.md">English</a>
|
|
18
|
+
</p>
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 📖 这是什么？
|
|
23
|
+
|
|
24
|
+
**CFShare** 是 [OpenClaw](https://github.com/openclaw/openclaw) 的社区插件，让你的 AI 助手能够：
|
|
25
|
+
|
|
26
|
+
- 🔗 **一键将本地端口**暴露为临时公网 HTTPS 链接（`https://*.trycloudflare.com`）
|
|
27
|
+
- 📁 **分享文件/目录**——自动起本地静态服务器 + 隧道，对方打开链接即可浏览/下载/预览（支持加密）
|
|
28
|
+
- 🔒 **内置安全策略**——Token/Basic 认证、速率限制、端口黑名单、排除规则
|
|
29
|
+
- ⏱️ **自动过期清理**——TTL 到期自动关闭隧道并删除临时文件
|
|
30
|
+
|
|
31
|
+
> [!NOTE]
|
|
32
|
+
> **无需 Cloudflare 账号**。CFShare 使用的是 [Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)（`trycloudflare.com`），完全免费、即开即用。
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 🏗️ 工作原理
|
|
37
|
+
|
|
38
|
+
```mermaid
|
|
39
|
+
flowchart LR
|
|
40
|
+
subgraph LOCAL["你的电脑"]
|
|
41
|
+
A["本地服务 / 文件"]
|
|
42
|
+
B["[可选] 反向代理<br/>(认证 + 限流)"]
|
|
43
|
+
C["cloudflared tunnel"]
|
|
44
|
+
|
|
45
|
+
A --> B
|
|
46
|
+
B --> C
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
C ==>|Cloudflare Quick Tunnel| D["https://xxx.trycloudflare.com"]
|
|
50
|
+
E["对方浏览器"] --> D
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
CFShare 在内部完成：路径校验 → 文件复制到临时目录 → 启动只读静态服务器 → 挂载认证/限流反代 → 开启 `cloudflared` 隧道 → 设置过期回收。你只需告诉 AI “我要分享什么”，它会帮你完成剩下的工作。
|
|
54
|
+
|
|
55
|
+
---
|
|
56
|
+
|
|
57
|
+
## 🚀 安装步骤
|
|
58
|
+
|
|
59
|
+
### 第一步：确保已安装 OpenClaw
|
|
60
|
+
|
|
61
|
+
如果你还没有安装 OpenClaw，请先完成安装：
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
# 安装 OpenClaw（需要 Node.js ≥ 22）
|
|
65
|
+
npm install -g openclaw@latest
|
|
66
|
+
|
|
67
|
+
# 运行初始化向导
|
|
68
|
+
openclaw onboard --install-daemon
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
> [!TIP]
|
|
72
|
+
> 如果你不确定 Node.js 版本，运行 `node -v` 检查。推荐使用 [nvm](https://github.com/nvm-sh/nvm) 管理版本。
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
### 第二步：安装 `cloudflared`
|
|
77
|
+
|
|
78
|
+
CFShare 依赖 Cloudflare 的 `cloudflared` 命令行工具来创建隧道。
|
|
79
|
+
|
|
80
|
+
<details>
|
|
81
|
+
<summary><b>🍎 macOS</b></summary>
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
brew install cloudflare/cloudflare/cloudflared
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
</details>
|
|
88
|
+
|
|
89
|
+
<details>
|
|
90
|
+
<summary><b>🐧 Linux（Debian / Ubuntu）</b></summary>
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
|
|
94
|
+
echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/cloudflared.list
|
|
95
|
+
sudo apt-get update && sudo apt-get install cloudflared
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
</details>
|
|
99
|
+
|
|
100
|
+
<details>
|
|
101
|
+
<summary><b>🪟 Windows（WSL2 内操作）</b></summary>
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
# 在 WSL2 中：
|
|
105
|
+
curl -fsSL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
|
|
106
|
+
chmod +x /usr/local/bin/cloudflared
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
或在 Windows 原生 PowerShell / CMD 中使用 winget：
|
|
110
|
+
|
|
111
|
+
```powershell
|
|
112
|
+
winget install --id Cloudflare.cloudflared
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
</details>
|
|
116
|
+
|
|
117
|
+
**或者直接告诉 Agent 让他帮你安装**
|
|
118
|
+
|
|
119
|
+
安装后验证：
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
cloudflared --version
|
|
123
|
+
# 输出类似: cloudflared version 2025.x.x
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
> [!IMPORTANT]
|
|
127
|
+
> 只需安装 `cloudflared`，**不需要**运行 `cloudflared tunnel login`。Quick Tunnel 无需账号认证。
|
|
128
|
+
|
|
129
|
+
---
|
|
130
|
+
|
|
131
|
+
### 第三步：安装 CFShare 插件
|
|
132
|
+
|
|
133
|
+
**方式 A — 从 npm 安装（推荐）：**
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
openclaw plugins install @ystemsrx/cfshare
|
|
137
|
+
# 安装完成后，重启 Gateway：
|
|
138
|
+
openclaw gateway restart
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**方式 B — 从本地目录安装（适用于开发）：**
|
|
142
|
+
|
|
143
|
+
如果你已经克隆了仓库：
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
# 先安装依赖
|
|
147
|
+
cd /path/to/cfshare
|
|
148
|
+
npm install
|
|
149
|
+
|
|
150
|
+
# 链接到 OpenClaw（开发模式，不复制文件）
|
|
151
|
+
openclaw plugins install -l .
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
### 第四步：启用插件并重启 Gateway
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
# 启用插件
|
|
160
|
+
openclaw plugins enable cfshare
|
|
161
|
+
|
|
162
|
+
# 重启 Gateway 使插件生效
|
|
163
|
+
openclaw gateway restart
|
|
164
|
+
```
|
|
165
|
+
|
|
166
166
|
> [!NOTE]
|
|
167
167
|
> 如果你使用守护进程模式（`--install-daemon`），也可以通过 `openclaw restart` 重启。
|
|
168
168
|
|
|
@@ -180,7 +180,7 @@ cfshare env_check
|
|
|
180
180
|
常用示例：
|
|
181
181
|
|
|
182
182
|
```bash
|
|
183
|
-
#
|
|
183
|
+
# 暴露已有本地服务
|
|
184
184
|
cfshare expose_port '{"port":3000,"opts":{"access":"token"}}'
|
|
185
185
|
|
|
186
186
|
# 分享文件/目录
|
|
@@ -190,177 +190,180 @@ cfshare expose_files '{"paths":["./dist"],"opts":{"access":"none"}}'
|
|
|
190
190
|
cfshare exposure_stop '{"id":"all"}'
|
|
191
191
|
```
|
|
192
192
|
|
|
193
|
-
`expose_port` 与 `expose_files`
|
|
194
|
-
|
|
193
|
+
`expose_port` 与 `expose_files` 默认会打印结果并退出。
|
|
194
|
+
如果你需要以前台方式保持生命周期管理（`Ctrl+C` 停止），可加 `--keep-alive`。
|
|
195
|
+
|
|
196
|
+
以 CLI 方式运行时，CFShare 默认使用 `~/.cfshare` 保存状态、workspace、策略和审计文件。
|
|
197
|
+
它与插件模式（`~/.openclaw/cfshare`）完全隔离，可同时存在、互不干扰。
|
|
195
198
|
|
|
196
199
|
---
|
|
197
200
|
|
|
198
201
|
## ⚙️ 配置（可选）
|
|
199
|
-
|
|
200
|
-
CFShare 开箱即用，以下默认配置适合绝大多数场景。如需调整，编辑 `~/.openclaw/openclaw.json`：
|
|
201
|
-
|
|
202
|
-
```json5
|
|
203
|
-
{
|
|
204
|
-
plugins: {
|
|
205
|
-
entries: {
|
|
206
|
-
cfshare: {
|
|
207
|
-
enabled: true,
|
|
208
|
-
config: {
|
|
209
|
-
// 自定义配置（以下皆为可选项）
|
|
210
|
-
},
|
|
211
|
-
},
|
|
212
|
-
},
|
|
213
|
-
},
|
|
214
|
-
}
|
|
215
|
-
```
|
|
216
|
-
|
|
217
|
-
### 可配置项速查
|
|
218
|
-
|
|
219
|
-
| 配置项 | 默认值 | 说明 |
|
|
220
|
-
| :------------------------- | :-------------------- | :----------------------------- |
|
|
221
|
-
| `cloudflaredPath` | `"cloudflared"` | `cloudflared` 的路径或名称 |
|
|
222
|
-
| `stateDir` | `~/.openclaw/cfshare` | 状态文件存储目录 |
|
|
223
|
-
| `defaultTtlSeconds` | `3600`（1 小时） | 默认隧道存活时间 |
|
|
224
|
-
| `maxTtlSeconds` | `86400`（24 小时） | 最大 TTL 上限 |
|
|
225
|
-
| `defaultExposePortAccess` | `"token"` | 端口暴露默认认证模式 |
|
|
226
|
-
| `defaultExposeFilesAccess` | `"none"` | 文件分享默认认证模式 |
|
|
227
|
-
| `blockedPorts` | `[22, 2375, 2376]` | 禁止暴露的端口（SSH / Docker） |
|
|
228
|
-
| `rateLimit.enabled` | `true` | 是否启用速率限制 |
|
|
229
|
-
| `rateLimit.maxRequests` | `240` | 每窗口期最大请求数 |
|
|
230
|
-
| `rateLimit.windowMs` | `60000`（1 分钟） | 速率限制窗口（毫秒） |
|
|
231
|
-
|
|
232
|
-
> [!TIP]
|
|
233
|
-
> **认证模式说明：**
|
|
234
|
-
>
|
|
235
|
-
> - `"token"` — 访问链接需要带 Token（适合暴露端口）
|
|
236
|
-
> - `"basic"` — HTTP Basic 认证（用户名/密码）
|
|
237
|
-
> - `"none"` — 无认证，任何人都可访问（适合临时分享文件）
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## 💬 使用示例
|
|
242
|
-
|
|
243
|
-
安装完成后，你可以直接对 AI 助手说自然语言，它会自动调用 CFShare 工具：
|
|
244
|
-
|
|
245
|
-
### 获取 AI 处理好的文件
|
|
246
|
-
|
|
247
|
-
> _按照 `{index}_{name}.{ext}` 的格式整理 `/mnt/data/students/` 下所有文件名，最后打包发我下载链接_
|
|
248
|
-
|
|
249
|
-
Agent 会自动执行 `expose_files`，返回一个公网链接和过期时间。
|
|
250
|
-
|
|
251
|
-
### 分享你的作品
|
|
252
|
-
|
|
253
|
-
> _"用 Vue3+Vite 框架完成3D交互式太阳系模型，然后用链接分享给我朋友"_
|
|
254
|
-
|
|
255
|
-
>_"帮我运行这个项目，最后把链接发我访问"_
|
|
256
|
-
|
|
257
|
-
Agent 会创建项目并运行，然后通过 `expose_port` 创建隧道，让任何人都能通过一个链接访问。
|
|
258
|
-
|
|
259
|
-
### 分享目录（带文件浏览器），可以在浏览器中预览图片/视频/文本等，也可以下载（支持加密）
|
|
260
|
-
|
|
261
|
-
> _"加密分享目录 `~/Pictures/vacation`"_
|
|
262
|
-
|
|
263
|
-
Agent 会用 `expose_files` 的 `preview` 模式创建带文件浏览器的分享页面，你需要拥有有效的 Token 才能访问。
|
|
264
|
-
|
|
265
|
-
### 查看活跃分享
|
|
266
|
-
|
|
267
|
-
> _"我现在有哪些正在分享的链接？"_
|
|
268
|
-
|
|
269
|
-
### 停止分享
|
|
270
|
-
|
|
271
|
-
> _"关掉所有正在分享的链接"_
|
|
272
|
-
|
|
273
|
-
---
|
|
274
|
-
|
|
275
|
-
## 🧰 工具一览
|
|
276
|
-
|
|
277
|
-
CFShare 为 AI 注册了以下工具：
|
|
278
|
-
|
|
279
|
-
| 工具 | 作用 |
|
|
280
|
-
| :-------------- | :------------------------------------ |
|
|
281
|
-
| `env_check` | 检查 `cloudflared` 是否可用及当前策略 |
|
|
282
|
-
| `expose_port` | 暴露本地端口到公网 |
|
|
283
|
-
| `expose_files` | 分享文件/目录（自动起静态服务器） |
|
|
284
|
-
| `exposure_list` | 列出所有活跃会话 |
|
|
285
|
-
| `exposure_get` | 获取指定会话详情 |
|
|
286
|
-
| `exposure_stop` | 停止并清理指定/全部会话 |
|
|
287
|
-
| `exposure_logs` | 查看会话日志 |
|
|
288
|
-
| `maintenance` | TTL 守护 / 垃圾回收 / 策略更新 |
|
|
289
|
-
| `audit_query` | 查询审计日志 |
|
|
290
|
-
| `audit_export` | 导出审计日志到文件 |
|
|
291
|
-
|
|
292
|
-
---
|
|
293
|
-
|
|
294
|
-
## 🔐 安全设计
|
|
295
|
-
|
|
296
|
-
<table>
|
|
297
|
-
<tr><td>🛡️</td><td><b>默认安全</b></td><td>端口暴露默认开启 Token 认证 + 反向代理保护</td></tr>
|
|
298
|
-
<tr><td>🚫</td><td><b>端口黑名单</b></td><td>SSH (22)、Docker Daemon (2375/2376) 默认禁止暴露</td></tr>
|
|
299
|
-
<tr><td>⏳</td><td><b>自动过期</b></td><td>会话到期自动关闭隧道并删除临时文件</td></tr>
|
|
300
|
-
<tr><td>📊</td><td><b>速率限制</b></td><td>Per-IP 滑动窗口限流（默认 240 次/分钟）</td></tr>
|
|
301
|
-
<tr><td>📝</td><td><b>审计日志</b></td><td>所有操作记录到本地 JSONL 文件</td></tr>
|
|
302
|
-
<tr><td>🙈</td><td><b>文件排除</b></td><td>自动排除 <code>.git/</code>、<code>.openclaw/</code>，并遵守 <code>.gitignore</code> 规则</td></tr>
|
|
303
|
-
</table>
|
|
304
|
-
|
|
305
|
-
---
|
|
306
|
-
|
|
307
|
-
## ❓ 常见问题
|
|
308
|
-
|
|
309
|
-
<details>
|
|
310
|
-
<summary><b>Q: 需要 Cloudflare 付费账号吗？</b></summary>
|
|
311
|
-
|
|
312
|
-
不需要。CFShare 使用 Cloudflare Quick Tunnel（`trycloudflare.com`），完全免费，无需注册账号。
|
|
313
|
-
|
|
314
|
-
</details>
|
|
315
|
-
|
|
316
|
-
<details>
|
|
317
|
-
<summary><b>Q: 链接有效期多长？</b></summary>
|
|
318
|
-
|
|
319
|
-
默认 1 小时，可通过配置或每次分享时指定（最长 7 天）。到期后自动销毁。
|
|
320
|
-
|
|
321
|
-
</details>
|
|
322
|
-
|
|
323
|
-
<details>
|
|
324
|
-
<summary><b>Q: cloudflared 提示找不到怎么办？</b></summary>
|
|
325
|
-
|
|
326
|
-
1. 确认 `cloudflared` 已安装：`cloudflared --version`
|
|
327
|
-
2. 如果安装位置不在 `PATH` 中，在配置里指定完整路径：
|
|
328
|
-
|
|
329
|
-
```json5
|
|
330
|
-
{
|
|
331
|
-
plugins: {
|
|
332
|
-
entries: {
|
|
333
|
-
cfshare: {
|
|
334
|
-
config: { cloudflaredPath: "/usr/local/bin/cloudflared" },
|
|
335
|
-
},
|
|
336
|
-
},
|
|
337
|
-
},
|
|
338
|
-
}
|
|
339
|
-
```
|
|
340
|
-
|
|
341
|
-
</details>
|
|
342
|
-
|
|
343
|
-
<details>
|
|
344
|
-
<summary><b>Q: 可以在 Windows 上直接用吗？</b></summary>
|
|
345
|
-
|
|
346
|
-
OpenClaw 官方强烈推荐在 Windows 上使用 WSL2。CFShare 同样遵循此建议，请在 WSL2 环境中使用。
|
|
347
|
-
|
|
348
|
-
</details>
|
|
349
|
-
|
|
350
|
-
<details>
|
|
351
|
-
<summary><b>Q: 如何验证插件是否安装成功？</b></summary>
|
|
352
|
-
|
|
353
|
-
```bash
|
|
354
|
-
openclaw plugins list
|
|
355
|
-
# 应该能看到 cfshare 处于 enabled 状态
|
|
356
|
-
```
|
|
357
|
-
|
|
358
|
-
然后对 AI 说 _"运行 cfshare 环境检查"_，它会调用 `env_check` 并返回详细状态。
|
|
359
|
-
|
|
360
|
-
</details>
|
|
361
|
-
|
|
362
|
-
---
|
|
363
|
-
|
|
364
|
-
## 📄 许可
|
|
365
|
-
|
|
366
|
-
MIT © [ystemsrx](https://github.com/ystemsrx)
|
|
202
|
+
|
|
203
|
+
CFShare 开箱即用，以下默认配置适合绝大多数场景。如需调整，编辑 `~/.openclaw/openclaw.json`：
|
|
204
|
+
|
|
205
|
+
```json5
|
|
206
|
+
{
|
|
207
|
+
plugins: {
|
|
208
|
+
entries: {
|
|
209
|
+
cfshare: {
|
|
210
|
+
enabled: true,
|
|
211
|
+
config: {
|
|
212
|
+
// 自定义配置（以下皆为可选项）
|
|
213
|
+
},
|
|
214
|
+
},
|
|
215
|
+
},
|
|
216
|
+
},
|
|
217
|
+
}
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### 可配置项速查
|
|
221
|
+
|
|
222
|
+
| 配置项 | 默认值 | 说明 |
|
|
223
|
+
| :------------------------- | :-------------------- | :----------------------------- |
|
|
224
|
+
| `cloudflaredPath` | `"cloudflared"` | `cloudflared` 的路径或名称 |
|
|
225
|
+
| `stateDir` | `~/.openclaw/cfshare` | 状态文件存储目录 |
|
|
226
|
+
| `defaultTtlSeconds` | `3600`（1 小时） | 默认隧道存活时间 |
|
|
227
|
+
| `maxTtlSeconds` | `86400`（24 小时） | 最大 TTL 上限 |
|
|
228
|
+
| `defaultExposePortAccess` | `"token"` | 端口暴露默认认证模式 |
|
|
229
|
+
| `defaultExposeFilesAccess` | `"none"` | 文件分享默认认证模式 |
|
|
230
|
+
| `blockedPorts` | `[22, 2375, 2376]` | 禁止暴露的端口（SSH / Docker） |
|
|
231
|
+
| `rateLimit.enabled` | `true` | 是否启用速率限制 |
|
|
232
|
+
| `rateLimit.maxRequests` | `240` | 每窗口期最大请求数 |
|
|
233
|
+
| `rateLimit.windowMs` | `60000`（1 分钟） | 速率限制窗口（毫秒） |
|
|
234
|
+
|
|
235
|
+
> [!TIP]
|
|
236
|
+
> **认证模式说明：**
|
|
237
|
+
>
|
|
238
|
+
> - `"token"` — 访问链接需要带 Token（适合暴露端口）
|
|
239
|
+
> - `"basic"` — HTTP Basic 认证（用户名/密码）
|
|
240
|
+
> - `"none"` — 无认证，任何人都可访问（适合临时分享文件）
|
|
241
|
+
|
|
242
|
+
---
|
|
243
|
+
|
|
244
|
+
## 💬 使用示例
|
|
245
|
+
|
|
246
|
+
安装完成后，你可以直接对 AI 助手说自然语言，它会自动调用 CFShare 工具：
|
|
247
|
+
|
|
248
|
+
### 获取 AI 处理好的文件
|
|
249
|
+
|
|
250
|
+
> _按照 `{index}_{name}.{ext}` 的格式整理 `/mnt/data/students/` 下所有文件名，最后打包发我下载链接_
|
|
251
|
+
|
|
252
|
+
Agent 会自动执行 `expose_files`，返回一个公网链接和过期时间。
|
|
253
|
+
|
|
254
|
+
### 分享你的作品
|
|
255
|
+
|
|
256
|
+
> _"用 Vue3+Vite 框架完成3D交互式太阳系模型，然后用链接分享给我朋友"_
|
|
257
|
+
|
|
258
|
+
>_"帮我运行这个项目，最后把链接发我访问"_
|
|
259
|
+
|
|
260
|
+
Agent 会创建项目并运行，然后通过 `expose_port` 创建隧道，让任何人都能通过一个链接访问。
|
|
261
|
+
|
|
262
|
+
### 分享目录（带文件浏览器），可以在浏览器中预览图片/视频/文本等，也可以下载（支持加密）
|
|
263
|
+
|
|
264
|
+
> _"加密分享目录 `~/Pictures/vacation`"_
|
|
265
|
+
|
|
266
|
+
Agent 会用 `expose_files` 的 `preview` 模式创建带文件浏览器的分享页面，你需要拥有有效的 Token 才能访问。
|
|
267
|
+
|
|
268
|
+
### 查看活跃分享
|
|
269
|
+
|
|
270
|
+
> _"我现在有哪些正在分享的链接？"_
|
|
271
|
+
|
|
272
|
+
### 停止分享
|
|
273
|
+
|
|
274
|
+
> _"关掉所有正在分享的链接"_
|
|
275
|
+
|
|
276
|
+
---
|
|
277
|
+
|
|
278
|
+
## 🧰 工具一览
|
|
279
|
+
|
|
280
|
+
CFShare 为 AI 注册了以下工具：
|
|
281
|
+
|
|
282
|
+
| 工具 | 作用 |
|
|
283
|
+
| :-------------- | :------------------------------------ |
|
|
284
|
+
| `env_check` | 检查 `cloudflared` 是否可用及当前策略 |
|
|
285
|
+
| `expose_port` | 暴露本地端口到公网 |
|
|
286
|
+
| `expose_files` | 分享文件/目录（自动起静态服务器） |
|
|
287
|
+
| `exposure_list` | 列出所有活跃会话 |
|
|
288
|
+
| `exposure_get` | 获取指定会话详情 |
|
|
289
|
+
| `exposure_stop` | 停止并清理指定/全部会话 |
|
|
290
|
+
| `exposure_logs` | 查看会话日志 |
|
|
291
|
+
| `maintenance` | TTL 守护 / 垃圾回收 / 策略更新 |
|
|
292
|
+
| `audit_query` | 查询审计日志 |
|
|
293
|
+
| `audit_export` | 导出审计日志到文件 |
|
|
294
|
+
|
|
295
|
+
---
|
|
296
|
+
|
|
297
|
+
## 🔐 安全设计
|
|
298
|
+
|
|
299
|
+
<table>
|
|
300
|
+
<tr><td>🛡️</td><td><b>默认安全</b></td><td>端口暴露默认开启 Token 认证 + 反向代理保护</td></tr>
|
|
301
|
+
<tr><td>🚫</td><td><b>端口黑名单</b></td><td>SSH (22)、Docker Daemon (2375/2376) 默认禁止暴露</td></tr>
|
|
302
|
+
<tr><td>⏳</td><td><b>自动过期</b></td><td>会话到期自动关闭隧道并删除临时文件</td></tr>
|
|
303
|
+
<tr><td>📊</td><td><b>速率限制</b></td><td>Per-IP 滑动窗口限流（默认 240 次/分钟）</td></tr>
|
|
304
|
+
<tr><td>📝</td><td><b>审计日志</b></td><td>所有操作记录到本地 JSONL 文件</td></tr>
|
|
305
|
+
<tr><td>🙈</td><td><b>文件排除</b></td><td>自动排除 <code>.git/</code>、<code>.openclaw/</code>，并遵守 <code>.gitignore</code> 规则</td></tr>
|
|
306
|
+
</table>
|
|
307
|
+
|
|
308
|
+
---
|
|
309
|
+
|
|
310
|
+
## ❓ 常见问题
|
|
311
|
+
|
|
312
|
+
<details>
|
|
313
|
+
<summary><b>Q: 需要 Cloudflare 付费账号吗？</b></summary>
|
|
314
|
+
|
|
315
|
+
不需要。CFShare 使用 Cloudflare Quick Tunnel（`trycloudflare.com`），完全免费，无需注册账号。
|
|
316
|
+
|
|
317
|
+
</details>
|
|
318
|
+
|
|
319
|
+
<details>
|
|
320
|
+
<summary><b>Q: 链接有效期多长？</b></summary>
|
|
321
|
+
|
|
322
|
+
默认 1 小时，可通过配置或每次分享时指定（最长 7 天）。到期后自动销毁。
|
|
323
|
+
|
|
324
|
+
</details>
|
|
325
|
+
|
|
326
|
+
<details>
|
|
327
|
+
<summary><b>Q: cloudflared 提示找不到怎么办？</b></summary>
|
|
328
|
+
|
|
329
|
+
1. 确认 `cloudflared` 已安装：`cloudflared --version`
|
|
330
|
+
2. 如果安装位置不在 `PATH` 中，在配置里指定完整路径：
|
|
331
|
+
|
|
332
|
+
```json5
|
|
333
|
+
{
|
|
334
|
+
plugins: {
|
|
335
|
+
entries: {
|
|
336
|
+
cfshare: {
|
|
337
|
+
config: { cloudflaredPath: "/usr/local/bin/cloudflared" },
|
|
338
|
+
},
|
|
339
|
+
},
|
|
340
|
+
},
|
|
341
|
+
}
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
</details>
|
|
345
|
+
|
|
346
|
+
<details>
|
|
347
|
+
<summary><b>Q: 可以在 Windows 上直接用吗？</b></summary>
|
|
348
|
+
|
|
349
|
+
OpenClaw 官方强烈推荐在 Windows 上使用 WSL2。CFShare 同样遵循此建议，请在 WSL2 环境中使用。
|
|
350
|
+
|
|
351
|
+
</details>
|
|
352
|
+
|
|
353
|
+
<details>
|
|
354
|
+
<summary><b>Q: 如何验证插件是否安装成功？</b></summary>
|
|
355
|
+
|
|
356
|
+
```bash
|
|
357
|
+
openclaw plugins list
|
|
358
|
+
# 应该能看到 cfshare 处于 enabled 状态
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
然后对 AI 说 _"运行 cfshare 环境检查"_，它会调用 `env_check` 并返回详细状态。
|
|
362
|
+
|
|
363
|
+
</details>
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## 📄 许可
|
|
368
|
+
|
|
369
|
+
MIT © [ystemsrx](https://github.com/ystemsrx)
|