specus

引水渠 —— 内网服务接入、网络打洞与流量观测。

specus 是项目的统一名称。项目以内网服务接入和私有组网为核心，Java 版本是当前基准实现；Go、C#、Android 与 C server 按统一 v2 协议持续对齐，源码自动化与真实环境验收范围见下文。C server 已解除轻量兼容子集冻结并进入 Java 全量对齐路线，但只有已经实现且通过实际门禁的能力才会标为完成。它在公网服务端和内网客户端之间维护控制连接，并在收到映射配置后，将公网 TCP/HTTP 流量转发到客户端可访问的本地服务；Peer Mesh 让同一用户下的多个客户端通过虚拟 IP 互访，数据面优先走 UDP direct，失败时回退到服务端标准 TURN relay。

当前 README 按 Java 基准实现维护；其它语言实现的覆盖范围见当前状态。

工作原理

flowchart TD
    U[公网访问者] -->|访问公网映射端口| P[TcpServer]
    P --> R[RemoteSpecusHandler]
    R <-->|通过 7010 控制连接传输数据| N[NatServerHandler]
    N <-->|Netty 自定义协议| C[NatClientHandler]
    C --> L[LocalSpecusHandler]
    L -->|访问内网地址和端口| S[本地 TCP 服务]
    H[HTTP 访问者] -->|访问 /http/client/route/path| W[HttpSpecusController]
    W <-->|通过 7010 控制连接直转 HTTP| C
    PM[PeerSignalService + 标准 STUN/TURN]
    A[客户端 A specus0] <-->|Peer Mesh UDP direct / relay| B[客户端 B specus0]
    A -.->|PEER_CONTROL / UDP probe| PM
    B -.->|PEER_CONTROL / UDP probe| PM

核心流程：

1. specus-server 启动 Spring Boot 应用，并在 7010 端口监听客户端控制连接。
2. specus-client 读取工作目录下的 client.jsonc（JSONC），先通过 HTTP apiKey/secret 登录，获取运行时 clientName、accessToken、控制连接地址和初始配置。
3. 客户端建立 Netty 控制连接并发送 LOGIN_REQUEST，服务端校验 token 后绑定在线会话。
4. 服务端向客户端发送 NAT_CONTROL 消息后，客户端动态添加 NatClientHandler 并注册端口映射。
5. 服务端为每个公网映射端口创建一个 TcpServer。
6. 公网请求到达映射端口后，数据经控制连接转发至客户端，再由客户端连接目标内网服务。
7. 开启 Peer Mesh 时，服务端通过 PEER_CONTROL 做设备列表、候选地址和 session 授权，客户端之间的数据面走加密 UDP direct，失败时回退到标准 TURN relay。

模块结构

模块	说明
implementations/java/common	Java 公共协议、编解码器、登录鉴权、心跳、会话、消息和同步 HTTP 请求能力，Maven artifact 为 specus-common
implementations/java/server	公网服务端（Java 参考实现），监听控制连接，并为已注册映射创建公网 TCP 监听端口，Maven artifact 为 specus-server
implementations/java/client	Java 内网客户端，连接服务端，并将隧道数据转发至目标内网服务，Maven artifact 为 specus-client
implementations/java/stun-server	Java 独立 RFC 5780 STUN 服务，支持四端点、限流、指标、CHANGE-REQUEST、RESPONSE-PORT 和 PADDING
apps/admin-web	管理后台前端(React + HeroUI)，构建产物供各服务端静态托管
deploy/java-server	Java server 的 systemd 安装、更新脚本和环境变量模板
deploy/stun-server	独立 STUN server 的 systemd 安装、更新脚本和四端点配置模板
deploy/go-server	Go server 的 Linux 交叉编译、SSH 远端部署、systemd 安装与回滚更新脚本
deploy/remote	从 macOS/Linux 或 Windows 将当前 Java server 与 OpenResty 前端一键构建、上传、更新并验收
deploy/migrations/specus-v1	从旧命名迁移到 Specus 的环境变量、systemd 路径和 SQLite/PostgreSQL/MySQL 数据库迁移工具
protocol/spec	跨语言协议说明、数据面/控制面规范入口
implementations/go/server	Go 服务端移植；同时提供独立 cmd/specus-stun-server 单文件 STUN 二进制
implementations/go/client	Go 内网客户端，与 Java 客户端使用相同配置和紧凑二进制协议
implementations/csharp/protocol	.NET 协议库，server/client 共同 ProjectReference 复用
implementations/csharp/server	.NET 服务端移植(EF Core,多库)；包含独立 Specus.StunServer 项目
implementations/csharp/client	.NET 内网客户端（CLI + Windows WPF 桌面客户端），与 Java/Go 客户端使用同一套 v2 线协议
implementations/android/client	Android 图形客户端，提供运行控制台、JSONC 配置、前台服务、TCP/HTTP 隧道、VpnService 和 Peer Mesh 基础数据面
implementations/c/server	C 服务端 Java 全量对齐实现（进行中）

主要入口：

• 服务端(Java)：implementations/java/server/src/main/java/com/theshuai/specusserver/SpecusServerApplication.java
• 独立 STUN(Java)：implementations/java/stun-server/src/main/java/com/theshuai/stunserver/StunServerApplication.java
• 独立 STUN(Go)：implementations/go/server/cmd/specus-stun-server/main.go
• 独立 STUN(.NET)：implementations/csharp/server/src/Specus.StunServer/Program.cs
• 服务端(Go)：implementations/go/server/cmd/specus-server/main.go
• 客户端(Java)：implementations/java/client/src/main/java/com/theshuai/specusclient/SpecusClientApplication.java
• 客户端(Go)：implementations/go/client/cmd/specus-client/main.go
• 客户端(.NET CLI)：implementations/csharp/client/src/Specus.Client/Program.cs
• 客户端(.NET 桌面)：implementations/csharp/client/src/Specus.Client.Desktop/MainWindow.xaml
• 客户端(Android)：implementations/android/client/app/src/main/java/com/theshuai/specus/android/MainActivity.java
• 管理后台前端：apps/admin-web/(npm run dev / npm run deploy:java|go|csharp)
• 协议实现：implementations/java/common/src/main/java/com/theshuai/common/protocol/PacketCodec.java

环境要求

• JDK 21
• Maven 3.x
• Node.js / npm（构建服务端管理后台静态资源时需要）
• Go 1.26（仅构建 Go 实现时需要）
• .NET 10 SDK（仅构建 .NET 实现时需要；Windows 桌面客户端目标框架为 net10.0-windows）

根目录 pom.xml 将 Java 编译版本设置为 21。仓库中的 Maven Wrapper 脚本没有可执行权限，且未提交 .mvn 目录，因此建议使用本机安装的 Maven。

构建

在项目根目录执行：

mvn clean install

只构建独立 STUN server：

mvn -pl :stun-server -am clean package
# implementations/java/stun-server/target/stun-server.jar

Go 与 .NET 独立 STUN：

cd implementations/go/server
go build ./cmd/specus-stun-server

dotnet build \
  implementations/csharp/server/src/Specus.StunServer/Specus.StunServer.csproj

specus-server 的 Maven 构建会在 generate-resources 阶段执行 apps/admin-web 的 npm run deploy:java：先构建 React 管理后台，再把 dist/ 只同步到 Java server 的 src/main/resources/static/。首次构建前请在 apps/admin-web 下执行一次 npm ci 安装依赖。 apps/admin-web/dist/ 和各 server 的静态同步目录都是构建产物,已在 .gitignore 中忽略,不要提交到仓库。

如只想构建后端、跳过前端打包与产物同步：

mvn clean install "-Dspecus.server.web.skip=true"

Go / C# server 构建各自处理自己的前端产物：C# 项目构建时执行 npm run deploy:csharp；Go server 使用 go generate ./web 执行 npm run deploy:go 后再 go build，这样不会改动其它 server 的静态目录。

.NET 实现统一使用 net10.0；CLI 客户端、服务端和 Windows 桌面客户端可在对应 implementations/csharp/* 目录下用 dotnet build / dotnet run 构建运行。

启动

1. 启动服务端

cd implementations/java/server
mvn org.springframework.boot:spring-boot-maven-plugin:run

服务端会监听两个端口：

端口	用途
7010	Netty 控制连接端口，默认值定义在 application.yml 中，可通过 SPECUS_NETTY_PORT 覆盖
8088	Spring Boot Web 和管理后台端口，定义在 application.yml 中

启动后访问 http://127.0.0.1:8088 可进入管理后台。管理后台支持用户名/密码与 OIDC 登录，管理 API 校验 Bearer JWT，详见管理后台登录。

This is the beginning of the README. Read the rest at the original. Read the full README ↗