# kproxy **Repository Path**: lmk73444/kproxy ## Basic Information - **Project Name**: kproxy - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-04 - **Last Updated**: 2026-05-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # kproxy 一个以"公网中心节点 + 多租户子网隔离 + 轻量化 GUI 客户端"为核心的代理网关。 --- ## 架构概览 ``` ┌──────────────────────────────────────┐ │ 公网 A (kpserver) │ │ │ admin ───────────►│ Vanilla JS Web Admin (embedded) │ │ REST API / SOCKS5 :1080 │ │ Agent Tunnel :7000 │ └──────────────┬───────────────────────┘ │ TLS + smux ┌─────────────────────┼─────────────────────┐ │ │ │ ┌────▼────┐ ┌────▼────┐ ┌────▼────┐ │ s1 │ │ s2 │ │ sn │ │ kpagent │ │ kpagent │ │ kpagent │ │ NAT后 │ │ NAT后 │ │ NAT后 │ └─────────┘ └─────────┘ └─────────┘ ┌─────────────┐ │ Go Client │ 本地 SOCKS5 :11080 │ (HTTP GUI) │◄──── 浏览器/WebView 控制面板 └─────────────┘ ``` ### 核心特性 - **三级权限**: System Admin → Subnet Admin → Subnet User - **多租户子网**: 默认同子网互通、跨子网隔离，支持显式 peering - **Peer 多子网接入**: 同一台机器可同时注册到多个 subnet - **Token 登录**: Subnet Admin 创建 user 并下发 client_token - **轻量 GUI**: Go 二进制 + 嵌入式 HTTP GUI，无需运行时 - **嵌入式 Web Admin**: subnet / user / token / peer / route 一站管理 --- ## 5 分钟快速体验 ```bash # 1. 启动本地完整环境 (kpserver + 2 agents + mock 内网 nginx) make local-up # 2. 通过 SOCKS5 访问内网服务 make local-test # 预期: {"service":"eng","message":"hello from eng backend"} ``` 启动后: | URL | 用途 | |---|---| | `http://localhost:8080` | Web 管理端 (admin/admin) | | `http://localhost:18080` | Client GUI (alice 视角) | | `socks5://localhost:1080` | SOCKS5 代理入口 | 清理: ```bash make local-down ``` --- ## 一条命令看完 REST API 全流程 `make local-up` 默认通过 SQL seed 预置了 prod / alice / s1 / s2 / web。 要观察 kproxy 的 REST API 在做什么，从 kpserver 容器一条命令完成 **subnet → user → membership → peer → route → client token**： ```bash docker exec kproxy-local-server sh -c ' KP=http://localhost:8080 echo "── 1. admin 登录" ADMIN=$(curl -sX POST $KP/api/auth/login -H "Content-Type: application/json" \ -d "{\"username\":\"admin\",\"password\":\"admin\"}" | jq -r .token) echo "── 2. 创建 demo 子网" SID=$(curl -sX POST $KP/api/subnets -H "Authorization: Bearer $ADMIN" \ -H "Content-Type: application/json" \ -d "{\"slug\":\"demo\",\"name\":\"Demo\"}" | jq -r .id) echo "── 3. 创建用户 bob 并加入 demo" UID=$(curl -sX POST $KP/api/users -H "Authorization: Bearer $ADMIN" \ -H "Content-Type: application/json" \ -d "{\"username\":\"bob\",\"password\":\"bob123\"}" | jq -r .id) curl -sX POST $KP/api/subnets/$SID/members -H "Authorization: Bearer $ADMIN" \ -H "Content-Type: application/json" \ -d "{\"user_id\":$UID,\"role\":\"user\"}" >/dev/null echo "── 4. 创建 peer + 绑定 route alias web→s1:80" curl -sX POST $KP/api/subnets/$SID/peers -H "Authorization: Bearer $ADMIN" \ -H "Content-Type: application/json" \ -d "{\"name\":\"demo-agent\",\"token\":\"kpa_demo_agent\",\"hostname\":\"demo-agent\",\"route_alias\":\"web\",\"target_host\":\"s1\",\"target_port\":80}" >/dev/null echo "── 5. bob 登录并申请 client token" BOB=$(curl -sX POST $KP/api/auth/login -H "Content-Type: application/json" \ -d "{\"username\":\"bob\",\"password\":\"bob123\"}" | jq -r .token) TOKEN=$(curl -sX POST $KP/api/me/tokens -H "Authorization: Bearer $BOB" \ -H "Content-Type: application/json" \ -d "{\"label\":\"laptop\"}" | jq -r .token) echo echo "✓ bootstrap 完成. bob client token: $TOKEN" echo " 注意: 本演示创建的 demo 子网无对应在线 agent (kpa_demo_agent 未启动)，仅用于验证 REST API 全流程。" echo " 真实可用的 SOCKS5 测试请用 seed 中的 alice → prod → web:" echo " curl --socks5-hostname alice:kpc_alice_local_token@localhost:1080 http://web.prod.kp/" ' ``` 完整 API 文档见 [doc/api-reference.md](doc/api-reference.md)，详细 Docker 演练见 [doc/quickstart.md](doc/quickstart.md)。 --- ## 核心概念 | 概念 | 说明 | 示例 | |---|---|---| | **Subnet** | 逻辑隔离的租户网络 | `prod`, `dev` | | **Peer** | 运行 kpagent 的内网机器 | `s1`, `s2` | | **Route Alias** | peer 上服务的命名别名 | `web` → `127.0.0.1:80` | | **Agent Token** | peer 接入 server 的凭证 | `kpa_xxx` | | **Client Token** | 用户 SOCKS5 登录密码 | `kpc_xxx` | SOCKS5 寻址 (route alias 优先, 找不到再回退到 peer-name): - `..kp[:port]` — 通过 route 别名 (推荐, port 可省略) - `..kp:` — 隐式端口，agent 直连 `127.0.0.1:` --- ## 生产部署 ### 1. 部署 kpserver ```bash docker build --target kpserver -t kproxy-server . mkdir -p data docker run -d --name kpserver -p 7000:7000 -p 8080:8080 -p 1080:1080 \ -v $(pwd)/data:/data kproxy-server -db /data/kpserver.db -dev ``` | 端口 | 用途 | |---|---| | `:7000` | Agent 隧道入口 (smux/TCP) | | `:8080` | REST API + Web 管理端 | | `:1080` | SOCKS5 代理入口 | 首次启动自动创建 system admin: `admin` / `admin`，请立即修改密码。 ### 2. 创建子网 / 用户 / peer / route 任选其一: - 浏览器打开 `http://:8080` 用 Web Admin UI 操作 - 用上面的 docker exec curl 一条命令演示完成 - 用 [doc/api-reference.md](doc/api-reference.md) 中的 curl 模板逐步执行 ### 3. 接入 Agent 在内网机器运行: ```bash ./bin/kpagent -server :7000 -token kpa_xxx -name s1 ``` 成功日志: ``` agent: connected to server addr=:7000 ``` ### 4. SOCKS5 访问 ```bash # Route alias (推荐) curl --socks5-hostname alice:kpc_xxx@:1080 http://web.prod.kp/ # 隐式端口 curl --socks5-hostname alice:kpc_xxx@:1080 http://s1.prod.kp:3306/ ``` 浏览器配置: 协议 SOCKS5, 服务器 `:1080`, 用户名/密码 = `alice` / `kpc_xxx`。 --- ## 开发 ```bash make dev # 启动 kpserver (data/kpserver.db, dev 模式) make dev-agent # 启动 kpagent 连本地 kpserver make dev-client # 启动 kpclient (本地 SOCKS5 :11080 + GUI :18080) ``` 构建: ```bash make build # server + agent + client 二进制 make docker # 三个 Docker 镜像 make e2e # 运行端到端测试 (Docker Compose) ``` --- ## 项目结构 ``` kproxy/ ├── cmd/{kpserver,kpagent,kpclient}/ # 三个二进制入口 ├── internal/ │ ├── auth/ # JWT / Token / Password │ ├── config/ # flag + env 配置 │ ├── policy/ # ACL 决策 │ ├── proto/ # 控制消息协议 │ ├── server/ # kpserver 核心 (server.go, socks5.go, relay.go, resolver.go, webui.go) │ ├── agent/ # kpagent 核心 │ ├── store/ # SQLite 数据访问 + migration │ └── tunnel/ # smux 隧道封装 ├── e2e/ # Docker Compose + Go 测试套件 ├── doc/ # quickstart.md / api-reference.md / todos.md ├── docker-compose.local.yml # 本地一键演示环境 ├── Dockerfile # 多阶段构建 (kpserver / kpagent / kpclient) └── Makefile ``` --- ## 数据模型要点 - **users**: 全局用户 + system_admin 标志 - **subnets**: 子网, 默认 peer_quota=16 / member_quota=16 - **subnet_members**: 用户↔子网, 角色 admin|user - **peers** + **peer_subscriptions**: peer 可注册到多个子网 - **routes**: peer 上的命名服务别名 - **subnet_peering** + **peering_routes**: 跨子网放行策略 - **client_tokens**: 用户 SOCKS5 登录 token - **sessions** / **audit_logs**: 连接审计 / 管理审计 --- ## 技术选型 | 层 | 选型 | 理由 | |---|---|---| | 服务端 | Go 1.24 | 网络栈强, 单二进制, 跨平台 | | 隧道复用 | smux | 单连接多 stream, NAT 友好 | | 认证 | argon2id + bcrypt + JWT | 分层安全 | | 数据库 | SQLite (WAL) | 嵌入式简单, 后期可切 Postgres | | Web Admin | Vanilla JS SPA (embedded) | 零构建依赖, 嵌入 Go binary | | 容器基础镜像 | `golang-1.24-bookworm` | 腾讯云 TCR + GOPROXY | --- ## 开发路线图 | 阶段 | 目标 | 状态 | |---|---|---| | M0 | 项目骨架 + 容器 | ✅ | | M1 | smux 隧道 + SOCKS5 直通 | ✅ | | M2 | 多租户 + SQLite + Token 认证 | ✅ (核心 API 完成, audit/peering API 待补) | | M3 | 子网隔离 + Peering + ACL | ✅ (基础, deny 规则待补) | | M4 | Web Admin + Tauri GUI | ✅ Web Admin / Tauri 预留 | | M5 | TLS + Metrics + 生产化 | ⏳ | 详细缺口和缺陷见 [doc/todos.md](doc/todos.md)。 --- ## 许可证 MIT