{"id":34612840,"url":"https://github.com/agent-network-protocol/anp-proxy","last_synced_at":"2025-12-24T14:17:47.749Z","repository":{"id":309188138,"uuid":"1033701649","full_name":"agent-network-protocol/anp-proxy","owner":"agent-network-protocol","description":"A reverse proxy service for the ANP protocol","archived":false,"fork":false,"pushed_at":"2025-08-10T11:28:58.000Z","size":214,"stargazers_count":2,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-10T13:06:20.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/agent-network-protocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-07T08:08:01.000Z","updated_at":"2025-08-10T11:29:01.000Z","dependencies_parsed_at":"2025-08-10T13:18:46.827Z","dependency_job_id":null,"html_url":"https://github.com/agent-network-protocol/anp-proxy","commit_stats":null,"previous_names":["agent-network-protocol/anp-proxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/agent-network-protocol/anp-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-network-protocol%2Fanp-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-network-protocol%2Fanp-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-network-protocol%2Fanp-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-network-protocol%2Fanp-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agent-network-protocol","download_url":"https://codeload.github.com/agent-network-protocol/anp-proxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agent-network-protocol%2Fanp-proxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28003727,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T14:17:46.438Z","updated_at":"2025-12-24T14:17:47.741Z","avatar_url":"https://github.com/agent-network-protocol.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ANP Proxy\n\nAgent Network Proxy (ANP) - 高性能 HTTP over WebSocket 隧道，用于私有网络服务的安全对外暴露。\n\n## 特性\n\n- 🚀 **高性能异步架构** - 基于 asyncio 的纯异步实现\n- 🔒 **安全可靠** - WSS (TLS) + 双向认证 + CRC 校验\n- 📦 **二进制协议** - 自定义 ANPX 协议，支持大文件分片传输\n- 🔧 **框架无关** - 支持任意 ASGI 应用 (FastAPI, Django, Flask 等)\n- 🔄 **自动重连** - 断线自动重连，指数退避策略\n- 📊 **监控友好** - 详细的日志和统计信息\n- ⚙️ **易于配置** - TOML 配置文件 + 命令行参数\n\n## 架构概览\n\n```\n┌────────────┐            WSS (TLS)           ┌──────────────┐\n│  Client    │ ─HTTP→ ┌──────────────┐ ─────→ │  Receiver \u0026  │\n│  外部调用者 │        │  Gateway     │        │  Internal App│\n└────────────┘ ←HTTP─ └──────────────┘ ←───── │  (FastAPI …) │\n                 ↑                ↓           └──────────────┘\n           Request 包装       Response 包装\n```\n\n## 快速开始\n\n### 安装\n\n```bash\n# 使用 UV 安装 (推荐)\nuv add anp-proxy\n\n# 或使用 pip\npip install anp-proxy\n```\n\n### 基本使用\n\n#### 1. 开发模式 (Gateway + Receiver 一体)\n\n```bash\n# 启动一体化代理，服务本地 FastAPI 应用\nanp-proxy --mode both --local-app \"myapp:app\" --gateway-port 8080\n```\n\n#### 2. 生产模式 - Gateway (公网部署)\n\n```bash\n# 在公网服务器启动 Gateway\nanp-proxy --mode gateway --gateway-host 0.0.0.0 --gateway-port 80 --wss-port 443\n```\n\n#### 3. 生产模式 - Receiver (私网部署)\n\n```bash\n# 在私网启动 Receiver，连接到公网 Gateway\nanp-proxy --mode receiver --gateway-url \"wss://your-gateway.com:443\" --local-app \"myapp:app\"\n```\n\n### 配置文件\n\n创建 `config.toml`:\n\n```toml\nmode = \"both\"  # gateway, receiver, both\n\n[gateway]\nhost = \"0.0.0.0\"\nport = 8080\nwss_port = 8765\n\n[receiver]\ngateway_url = \"wss://localhost:8765\"\nlocal_app_module = \"myapp:app\"\n\n[logging]\nlevel = \"INFO\"\n```\n\n使用配置文件：\n\n```bash\nanp-proxy --config config.toml\n```\n\n## 详细配置\n\n### Gateway 配置\n\n```toml\n[gateway]\n# HTTP 服务器设置\nhost = \"0.0.0.0\"\nport = 8080\n\n# WebSocket 服务器设置\nwss_host = \"0.0.0.0\"\nwss_port = 8765\n\n# 连接设置\nmax_connections = 100\ntimeout = 30.0\nchunk_size = 65536  # 64KB\n\n[gateway.tls]\nenabled = true\ncert_file = \"server.crt\"\nkey_file = \"server.key\"\nverify_mode = \"required\"\n\n[gateway.auth]\nenabled = true\nshared_secret = \"your-secret-key\"\ntoken_expiry = 3600\n```\n\n### Receiver 配置\n\n```toml\n[receiver]\n# Gateway 连接\ngateway_url = \"wss://gateway.example.com:8765\"\n\n# 本地应用设置\nlocal_app_module = \"myapp:app\"  # ASGI 应用\n\n# 重连设置\nreconnect_enabled = true\nreconnect_delay = 5.0\nmax_reconnect_attempts = 10\n\n[receiver.tls]\nenabled = true\nca_file = \"ca.crt\"\nverify_mode = \"required\"\n\n[receiver.auth]\nenabled = true\nshared_secret = \"your-secret-key\"\n```\n\n## Python API\n\n### 编程方式使用\n\n```python\nimport asyncio\nfrom anp_proxy import ANPProxy, ANPConfig\n\n# 创建配置\nconfig = ANPConfig(mode=\"both\")\nconfig.gateway.port = 8080\nconfig.receiver.local_app_module = \"myapp:app\"\n\n# 创建并运行代理\nasync def main():\n    proxy = ANPProxy(config)\n    \n    if config.mode == \"gateway\":\n        gateway = proxy.create_gateway_server()\n        await gateway.run()\n    elif config.mode == \"receiver\":\n        receiver = proxy.create_receiver_client()\n        await receiver.run()\n\nasyncio.run(main())\n```\n\n### 集成到现有应用\n\n```python\nfrom fastapi import FastAPI\nfrom anp_proxy import ReceiverClient, ReceiverConfig\n\napp = FastAPI()\n\n@app.get(\"/\")\nasync def root():\n    return {\"message\": \"Hello World\"}\n\n# 创建 ANP Receiver\nconfig = ReceiverConfig(gateway_url=\"wss://gateway.example.com:8765\")\nreceiver = ReceiverClient(config, app)\n\n# 启动 receiver (在后台任务中)\nimport asyncio\nasyncio.create_task(receiver.run())\n```\n\n## ANPX 协议\n\nANP Proxy 使用自定义的 ANPX 二进制协议，支持：\n\n- **固定 24B 头部** - 魔数、版本、类型、标志、长度、CRC 校验\n- **TLV 扩展体** - 灵活的标签-长度-值格式\n- **分片传输** - 支持大文件和流式内容\n- **端到端校验** - CRC-32 双层校验保证数据完整性\n\n详细协议规范请参考 [docs/proxy-protocol.md](docs/proxy-protocol.md)\n\n## 监控和运维\n\n### 健康检查\n\n```bash\n# 检查 Gateway 状态\ncurl http://localhost:8080/health\n\n# 获取统计信息\ncurl http://localhost:8080/stats\n```\n\n### 日志配置\n\n```toml\n[logging]\nlevel = \"INFO\"  # DEBUG, INFO, WARNING, ERROR\nformat = \"%(asctime)s [%(levelname)s] %(name)s: %(message)s\"\nfile = \"anp-proxy.log\"\nmax_size = \"10MB\"\nbackup_count = 5\n```\n\n### 性能调优\n\n```toml\n[gateway]\nchunk_size = 131072  # 128KB，适合大文件传输\nmax_connections = 1000  # 最大连接数\ntimeout = 60.0  # 超时时间\n\n[receiver]\nchunk_size = 131072\nreconnect_delay = 2.0  # 重连延迟\n```\n\n## 部署示例\n\n### Docker 部署\n\n```dockerfile\nFROM python:3.11-slim\n\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install -r requirements.txt\n\nCOPY . .\nEXPOSE 8080 8765\n\nCMD [\"anp-proxy\", \"--config\", \"config.toml\"]\n```\n\n### Systemd 服务\n\n```ini\n[Unit]\nDescription=ANP Proxy Gateway\nAfter=network.target\n\n[Service]\nType=exec\nUser=anp-proxy\nWorkingDirectory=/opt/anp-proxy\nExecStart=/opt/anp-proxy/venv/bin/anp-proxy --config config.toml\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\n## 故障排除\n\n### 常见问题\n\n1. **连接失败**\n   - 检查防火墙设置\n   - 验证 WebSocket URL 是否正确\n   - 确认 TLS 证书配置\n\n2. **认证失败**\n   - 检查 shared_secret 是否一致\n   - 验证时间同步 (重要)\n\n3. **性能问题**\n   - 调整 chunk_size\n   - 增加 max_connections\n   - 检查网络延迟\n\n### 调试模式\n\n```bash\nanp-proxy --debug --log-level DEBUG\n```\n\n## 许可证\n\nMIT License - 详见 [LICENSE](LICENSE) 文件\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 支持\n\n- 📖 [文档](docs/)\n- 🐛 [Issue Tracker](https://github.com/your-org/anp-proxy/issues)\n- 💬 [讨论区](https://github.com/your-org/anp-proxy/discussions)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-network-protocol%2Fanp-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagent-network-protocol%2Fanp-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagent-network-protocol%2Fanp-proxy/lists"}