https://github.com/agent-network-protocol/anp-proxy
A reverse proxy service for the ANP protocol
https://github.com/agent-network-protocol/anp-proxy
Last synced: 3 months ago
JSON representation
A reverse proxy service for the ANP protocol
- Host: GitHub
- URL: https://github.com/agent-network-protocol/anp-proxy
- Owner: agent-network-protocol
- License: apache-2.0
- Created: 2025-08-07T08:08:01.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-08-10T11:28:58.000Z (7 months ago)
- Last Synced: 2025-08-10T13:06:20.251Z (7 months ago)
- Language: Python
- Size: 209 KB
- Stars: 2
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ANP Proxy
Agent Network Proxy (ANP) - 高性能 HTTP over WebSocket 隧道，用于私有网络服务的安全对外暴露。
## 特性
- 🚀 **高性能异步架构** - 基于 asyncio 的纯异步实现
- 🔒 **安全可靠** - WSS (TLS) + 双向认证 + CRC 校验
- 📦 **二进制协议** - 自定义 ANPX 协议，支持大文件分片传输
- 🔧 **框架无关** - 支持任意 ASGI 应用 (FastAPI, Django, Flask 等)
- 🔄 **自动重连** - 断线自动重连，指数退避策略
- 📊 **监控友好** - 详细的日志和统计信息
- ⚙️ **易于配置** - TOML 配置文件 + 命令行参数
## 架构概览
```
┌────────────┐ WSS (TLS) ┌──────────────┐
│ Client │ ─HTTP→ ┌──────────────┐ ─────→ │ Receiver & │
│ 外部调用者 │ │ Gateway │ │ Internal App│
└────────────┘ ←HTTP─ └──────────────┘ ←───── │ (FastAPI …) │
↑ ↓ └──────────────┘
Request 包装 Response 包装
```
## 快速开始
### 安装
```bash
# 使用 UV 安装 (推荐)
uv add anp-proxy
# 或使用 pip
pip install anp-proxy
```
### 基本使用
#### 1. 开发模式 (Gateway + Receiver 一体)
```bash
# 启动一体化代理，服务本地 FastAPI 应用
anp-proxy --mode both --local-app "myapp:app" --gateway-port 8080
```
#### 2. 生产模式 - Gateway (公网部署)
```bash
# 在公网服务器启动 Gateway
anp-proxy --mode gateway --gateway-host 0.0.0.0 --gateway-port 80 --wss-port 443
```
#### 3. 生产模式 - Receiver (私网部署)
```bash
# 在私网启动 Receiver，连接到公网 Gateway
anp-proxy --mode receiver --gateway-url "wss://your-gateway.com:443" --local-app "myapp:app"
```
### 配置文件
创建 `config.toml`:
```toml
mode = "both" # gateway, receiver, both
[gateway]
host = "0.0.0.0"
port = 8080
wss_port = 8765
[receiver]
gateway_url = "wss://localhost:8765"
local_app_module = "myapp:app"
[logging]
level = "INFO"
```
使用配置文件：
```bash
anp-proxy --config config.toml
```
## 详细配置
### Gateway 配置
```toml
[gateway]
# HTTP 服务器设置
host = "0.0.0.0"
port = 8080
# WebSocket 服务器设置
wss_host = "0.0.0.0"
wss_port = 8765
# 连接设置
max_connections = 100
timeout = 30.0
chunk_size = 65536 # 64KB
[gateway.tls]
enabled = true
cert_file = "server.crt"
key_file = "server.key"
verify_mode = "required"
[gateway.auth]
enabled = true
shared_secret = "your-secret-key"
token_expiry = 3600
```
### Receiver 配置
```toml
[receiver]
# Gateway 连接
gateway_url = "wss://gateway.example.com:8765"
# 本地应用设置
local_app_module = "myapp:app" # ASGI 应用
# 重连设置
reconnect_enabled = true
reconnect_delay = 5.0
max_reconnect_attempts = 10
[receiver.tls]
enabled = true
ca_file = "ca.crt"
verify_mode = "required"
[receiver.auth]
enabled = true
shared_secret = "your-secret-key"
```
## Python API
### 编程方式使用
```python
import asyncio
from anp_proxy import ANPProxy, ANPConfig
# 创建配置
config = ANPConfig(mode="both")
config.gateway.port = 8080
config.receiver.local_app_module = "myapp:app"
# 创建并运行代理
async def main():
proxy = ANPProxy(config)
if config.mode == "gateway":
gateway = proxy.create_gateway_server()
await gateway.run()
elif config.mode == "receiver":
receiver = proxy.create_receiver_client()
await receiver.run()
asyncio.run(main())
```
### 集成到现有应用
```python
from fastapi import FastAPI
from anp_proxy import ReceiverClient, ReceiverConfig
app = FastAPI()
@app.get("/")
async def root():
return {"message": "Hello World"}
# 创建 ANP Receiver
config = ReceiverConfig(gateway_url="wss://gateway.example.com:8765")
receiver = ReceiverClient(config, app)
# 启动 receiver (在后台任务中)
import asyncio
asyncio.create_task(receiver.run())
```
## ANPX 协议
ANP Proxy 使用自定义的 ANPX 二进制协议，支持：
- **固定 24B 头部** - 魔数、版本、类型、标志、长度、CRC 校验
- **TLV 扩展体** - 灵活的标签-长度-值格式
- **分片传输** - 支持大文件和流式内容
- **端到端校验** - CRC-32 双层校验保证数据完整性
详细协议规范请参考 [docs/proxy-protocol.md](docs/proxy-protocol.md)
## 监控和运维
### 健康检查
```bash
# 检查 Gateway 状态
curl http://localhost:8080/health
# 获取统计信息
curl http://localhost:8080/stats
```
### 日志配置
```toml
[logging]
level = "INFO" # DEBUG, INFO, WARNING, ERROR
format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
file = "anp-proxy.log"
max_size = "10MB"
backup_count = 5
```
### 性能调优
```toml
[gateway]
chunk_size = 131072 # 128KB，适合大文件传输
max_connections = 1000 # 最大连接数
timeout = 60.0 # 超时时间
[receiver]
chunk_size = 131072
reconnect_delay = 2.0 # 重连延迟
```
## 部署示例
### Docker 部署
```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8080 8765
CMD ["anp-proxy", "--config", "config.toml"]
```
### Systemd 服务
```ini
[Unit]
Description=ANP Proxy Gateway
After=network.target
[Service]
Type=exec
User=anp-proxy
WorkingDirectory=/opt/anp-proxy
ExecStart=/opt/anp-proxy/venv/bin/anp-proxy --config config.toml
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
```
## 故障排除
### 常见问题
1. **连接失败**
- 检查防火墙设置
- 验证 WebSocket URL 是否正确
- 确认 TLS 证书配置
2. **认证失败**
- 检查 shared_secret 是否一致
- 验证时间同步 (重要)
3. **性能问题**
- 调整 chunk_size
- 增加 max_connections
- 检查网络延迟
### 调试模式
```bash
anp-proxy --debug --log-level DEBUG
```
## 许可证
MIT License - 详见 [LICENSE](LICENSE) 文件
## 贡献
欢迎提交 Issue 和 Pull Request！
## 支持
- 📖 [文档](docs/)
- 🐛 [Issue Tracker](https://github.com/your-org/anp-proxy/issues)
- 💬 [讨论区](https://github.com/your-org/anp-proxy/discussions)