CyberMind-FR
ccfb58124c
Add complete French (fr) and Chinese (zh) translations for all documentation: - Root files: README, CHANGELOG, SECURITY, BETA-RELEASE - docs/: All 16 core documentation files - DOCS/: All 19 deep-dive documents including embedded/ and archive/ - package/secubox/: All 123+ package READMEs - Misc: secubox-tools/, scripts/, EXAMPLES/, config-backups/, streamlit-apps/ Total: 346 translation files created Each file includes language switcher links for easy navigation between English, French, and Chinese versions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
246 lines
9.7 KiB
Markdown
246 lines
9.7 KiB
Markdown
# Punk Exposure Engine
|
||
|
||
> **Languages**: [English](PUNK-EXPOSURE.md) | [Francais](PUNK-EXPOSURE.fr.md) | 中文
|
||
|
||
## 愿景
|
||
|
||
每个 SecuBox 节点都是一个**生成式站点** — 它发现本地运行的服务，并提供统一的流程使任何服务可通过所有可用渠道访问：Tor .onion、传统 DNS/HTTPS、P2P 网状网络，或三者同时。
|
||
|
||
三个动词定义了工作流程：
|
||
|
||
- **Peek** — 扫描、发现、观察。什么在运行？什么已暴露？哪些域名已映射？哪些节点在线？
|
||
- **Poke** — 针对一个服务。选择暴露渠道。配置链接流程。
|
||
- **Emancipate** — 激活。服务变为可访问。DNS 记录被创建，证书被颁发，.onion 地址被生成，网状网络节点被通知。
|
||
|
||
## 架构
|
||
|
||
```
|
||
EMANCIPATE
|
||
|
|
||
+----------------+----------------+
|
||
| | |
|
||
Tor Layer DNS/SSL Layer Mesh Layer
|
||
(.onion) (HTTPS+ACME) (P2P peers)
|
||
| | |
|
||
tor-shield haproxyctl secubox-p2p
|
||
hidden svc + dns-provider-api + gossip sync
|
||
+ acme.sh
|
||
|
|
||
DNS Provider APIs
|
||
(OVH, Gandi, Cloudflare)
|
||
|
|
||
A/AAAA/CNAME records
|
||
created programmatically
|
||
```
|
||
|
||
## 组件
|
||
|
||
### 现有组件（已构建）
|
||
|
||
| 组件 | 包名 | 功能 |
|
||
|-----------|---------|--------------|
|
||
| 服务扫描器 | `secubox-app-exposure` | 使用 UCI/Docker/进程名称增强的 `netstat` 扫描 |
|
||
| Tor 暴露 | `secubox-app-tor` + `secubox-app-exposure` | `tor_add()` 创建隐藏服务目录 + torrc 条目 |
|
||
| SSL/HAProxy 暴露 | `secubox-app-haproxy` + `secubox-app-exposure` | `ssl_add()` 创建 HAProxy 后端 + vhost + ACME 证书 |
|
||
| ACME 证书 | `secubox-app-haproxy` | `acme.sh` 通过端口 8402 进行 HTTP-01 webroot 验证 |
|
||
| VHost 管理器 | `luci-app-vhost-manager` | 基于 Nginx 的 vhost CRUD，支持 ACME + 模板 |
|
||
| P2P 网状网络 | `secubox-p2p` | mDNS 发现、WireGuard 网状网络、服务注册表、gossip 链 |
|
||
| Master-Link | `secubox-master-link` | 使用 HMAC 令牌的层级节点接入 + 区块链审计 |
|
||
| 服务注册表 | `luci-app-service-registry` | 跨网状网络聚合服务、健康检查、着陆页 |
|
||
| Exposure 仪表板 | `luci-app-exposure` | KISS 单表视图：扫描 + 每个服务的 Tor/SSL 开关 |
|
||
|
||
### 缺失组件（待构建）
|
||
|
||
| 组件 | 目的 | 优先级 |
|
||
|-----------|---------|----------|
|
||
| **DNS 供应商 API** | 程序化 DNS 记录管理 (OVH, Gandi, Cloudflare) | **高** |
|
||
| **DNS-01 ACME** | 通配符证书 + 无端口 80 访问的域名 | **高** |
|
||
| **统一 Poke 流程** | 单一操作在所有渠道暴露服务 | 中等 |
|
||
| **Peek 聚合** | 组合视图：本地扫描 + 网状网络节点 + DNS 记录 + Tor | 中等 |
|
||
| **Emancipate 编排器** | 支持回滚的原子多渠道激活 | 中等 |
|
||
|
||
## DNS 供应商 API 集成
|
||
|
||
### 设计
|
||
|
||
新包：`secubox-app-dns-provider`
|
||
|
||
```
|
||
package/secubox/secubox-app-dns-provider/
|
||
files/etc/config/dns-provider # UCI: 供应商类型、API 密钥、区域
|
||
files/etc/init.d/dns-provider # (可选) 记录同步 cron
|
||
files/usr/sbin/dnsctl # CLI: record add/rm/list/sync
|
||
files/usr/lib/secubox/dns/ # 供应商适配器
|
||
ovh.sh # OVH API (app key + secret + consumer key)
|
||
gandi.sh # Gandi LiveDNS (API 密钥)
|
||
cloudflare.sh # Cloudflare (API 令牌 + zone ID)
|
||
```
|
||
|
||
### UCI 配置
|
||
|
||
```uci
|
||
config dns_provider 'main'
|
||
option enabled '1'
|
||
option provider 'ovh' # ovh | gandi | cloudflare
|
||
option zone 'example.com' # 管理的 DNS 区域
|
||
|
||
config ovh 'ovh'
|
||
option endpoint 'ovh-eu' # ovh-eu | ovh-ca | ovh-us
|
||
option app_key ''
|
||
option app_secret ''
|
||
option consumer_key ''
|
||
|
||
config gandi 'gandi'
|
||
option api_key ''
|
||
|
||
config cloudflare 'cloudflare'
|
||
option api_token ''
|
||
option zone_id ''
|
||
```
|
||
|
||
### dnsctl 命令
|
||
|
||
```
|
||
dnsctl list # 列出区域中所有 DNS 记录
|
||
dnsctl add A myservice 1.2.3.4 # 创建 A 记录
|
||
dnsctl add CNAME blog mycdn.net # 创建 CNAME
|
||
dnsctl rm A myservice # 删除记录
|
||
dnsctl sync # 将本地 vhosts 同步到 DNS 记录
|
||
dnsctl verify myservice.example.com # 检查 DNS 传播
|
||
```
|
||
|
||
### acme.sh DNS-01 集成
|
||
|
||
一旦 `dnsctl` 工作正常，在 `haproxyctl cert add` 中启用 DNS-01 挑战：
|
||
|
||
```sh
|
||
# 当前 (仅 HTTP-01):
|
||
acme.sh --issue -d "$domain" --webroot /var/www/acme-challenge
|
||
|
||
# 新方式 (通过供应商的 DNS-01):
|
||
provider=$(uci -q get dns-provider.main.provider)
|
||
case "$provider" in
|
||
ovh)
|
||
export OVH_END_POINT=$(uci -q get dns-provider.ovh.endpoint)
|
||
export OVH_APPLICATION_KEY=$(uci -q get dns-provider.ovh.app_key)
|
||
export OVH_APPLICATION_SECRET=$(uci -q get dns-provider.ovh.app_secret)
|
||
export OVH_CONSUMER_KEY=$(uci -q get dns-provider.ovh.consumer_key)
|
||
acme.sh --issue -d "$domain" --dns dns_ovh
|
||
;;
|
||
gandi)
|
||
export GANDI_LIVEDNS_KEY=$(uci -q get dns-provider.gandi.api_key)
|
||
acme.sh --issue -d "$domain" --dns dns_gandi_livedns
|
||
;;
|
||
cloudflare)
|
||
export CF_Token=$(uci -q get dns-provider.cloudflare.api_token)
|
||
export CF_Zone_ID=$(uci -q get dns-provider.cloudflare.zone_id)
|
||
acme.sh --issue -d "$domain" --dns dns_cf
|
||
;;
|
||
esac
|
||
```
|
||
|
||
这解锁了**通配符证书** (`*.example.com`) 和防火墙后面没有端口 80 的域名。
|
||
|
||
## Emancipate 流程
|
||
|
||
当用户 poke 一个服务并选择 "Emancipate" 时，编排器原子地运行所有选定的渠道：
|
||
|
||
```
|
||
用户选择：Gitea (端口 3001) → Emancipate [Tor + DNS + Mesh]
|
||
|
||
1. Tor 渠道:
|
||
secubox-exposure tor add gitea 3001 80
|
||
→ 生成 .onion 地址
|
||
|
||
2. DNS 渠道:
|
||
dnsctl add A gitea <public-ip>
|
||
haproxyctl vhost add gitea.example.com 3001
|
||
haproxyctl cert add gitea.example.com --dns
|
||
→ HTTPS 在 gitea.example.com 上线
|
||
|
||
3. Mesh 渠道:
|
||
secubox-p2p publish gitea 3001 "Gitea"
|
||
gossip_sync
|
||
→ 所有网状网络节点发现该服务
|
||
|
||
4. 注册表更新:
|
||
服务注册表刷新
|
||
着陆页重新生成
|
||
Exposure 仪表板显示三个徽章
|
||
```
|
||
|
||
### 失败时回滚
|
||
|
||
如果任何渠道失败，先前完成的渠道不会被拆除 — 它们保持活动状态。失败会被报告，用户可以通过 Exposure 仪表板的开关重试或删除单个渠道。
|
||
|
||
## Peek：当前存在的功能
|
||
|
||
当前的 Exposure 仪表板 (`luci-app-exposure/services.js`) 已经实现了 Peek：
|
||
|
||
- 通过 `netstat -tlnp` 扫描所有监听端口
|
||
- 使用来自 uhttpd、streamlit、Docker、glances 配置的真实名称进行增强
|
||
- 通过后端端口交叉引用 Tor 隐藏服务
|
||
- 通过后端端口交叉引用 HAProxy vhosts
|
||
- 显示每个服务的 Tor 和 SSL 开关
|
||
|
||
### Peek 下一步需要
|
||
|
||
- **DNS 记录列** ：通过 `dnsctl list` 显示哪些服务有 DNS A/CNAME 记录
|
||
- **Mesh 可见性列**：显示哪些服务已发布到网状网络节点
|
||
- **多节点视图**：聚合所有网状网络节点的服务（已通过 `secubox-p2p get_shared_services` 可用）
|
||
|
||
## Poke：当前存在的功能
|
||
|
||
Exposure 仪表板中的开关已经是 "Poke" 操作：
|
||
|
||
- 切换 Tor ON → 模态框 → 服务名称 + onion 端口 → 启用
|
||
- 切换 SSL ON → 模态框 → 服务名称 + 域名 → 启用
|
||
|
||
### Poke 下一步需要
|
||
|
||
- **DNS 开关**：用于 DNS 记录管理的第三个开关列
|
||
- **Emancipate 按钮**：每个服务的 "全渠道暴露" 单一操作
|
||
- **供应商选择**：为域名选择哪个 DNS 区域/供应商
|
||
|
||
## 与现有包的集成点
|
||
|
||
| 包名 | 集成 | 方向 |
|
||
|---------|------------|-----------|
|
||
| `secubox-app-exposure` | Peek 扫描 + Tor/SSL 添加/删除 | 已工作 |
|
||
| `secubox-app-haproxy` | HAProxy vhost + ACME 证书 | 已工作 |
|
||
| `secubox-app-tor` | 隐藏服务生命周期 | 已工作 |
|
||
| `secubox-p2p` | 服务发布 + gossip 同步 | 添加 `publish` RPC 调用 |
|
||
| `luci-app-exposure` | 仪表板：添加 DNS 列 + Emancipate 按钮 | 前端扩展 |
|
||
| `secubox-app-dns-provider` | **新建**：通过供应商 API 的 DNS 记录 CRUD | 待构建 |
|
||
| `luci-app-dns-provider` | **新建**：供应商凭据的 LuCI 配置 | 待构建 |
|
||
|
||
## 实施顺序
|
||
|
||
1. **`secubox-app-dns-provider`** — CLI 工具 + UCI 配置 + 供应商适配器（先 OVH）
|
||
2. **haproxyctl 中的 DNS-01** — 将 `dnsctl` 连接到 ACME 流程作为 HTTP-01 的替代
|
||
3. **`luci-app-dns-provider`** — 供应商配置的 LuCI 前端
|
||
4. **Exposure 仪表板 DNS 列** — 添加 DNS 开关 + `dnsctl` 集成
|
||
5. **Emancipate 流程** — `secubox-exposure emancipate` 中的统一编排器
|
||
6. **Mesh 发布集成** — 将 `secubox-p2p publish` 连接到 Emancipate
|
||
|
||
## 命名约定
|
||
|
||
该项目使用朋克/DIY 隐喻：
|
||
|
||
| 术语 | 含义 | 技术等价物 |
|
||
|------|---------|---------------------|
|
||
| **Peek** | 发现、扫描、观察 | `secubox-exposure scan` + 服务注册表 |
|
||
| **Poke** | 瞄准、配置、对准 | 开关 + 模态配置 |
|
||
| **Emancipate** | 激活、释放、暴露 | 原子多渠道激活 |
|
||
| **Station** | 一个 SecuBox 节点 | 运行网状网络的 OpenWrt 设备 |
|
||
| **Generative** | 每个站点可以创建新端点 | Docker 应用 + 暴露渠道 |
|
||
|
||
## 安全考虑
|
||
|
||
- DNS 供应商 API 密钥存储在带有受限 ACL 的 UCI 中
|
||
- ACME 私钥在 `/etc/acme/` 中，权限为 600
|
||
- Tor 隐藏服务密钥在 `/var/lib/tor/` 中，所有者为 tor:tor
|
||
- Emancipate 流程永远不会暴露仅 127.0.0.1 的服务（扫描中有守卫）
|
||
- DNS 记录仅为用户明确 Poke 的服务创建
|
||
- 回滚不会自动删除 — 用户必须明确移除暴露
|