pubgo · kooksee · Jul 6, 2026 · Jul 5, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -8,7 +8,7 @@ These instructions are project-wide defaults for this repository. Keep changes f
 
 - `lava/`: core public interfaces and contracts (`Middleware`, routers, request/response abstractions).
 - `core/`: runtime capabilities (supervisor, scheduler, tunnel, logging/metrics/tracing, debug, DI builder).
-- `servers/`: service hosts (`https` on Fiber, `grpcs` with gateway integration).
+- `servers/`: service hosts (`gatewayserver` multi-protocol gateway, `https` on Fiber, `zrpcs` on NATS).
 - `clients/`: outbound client implementations (`grpcc`, `resty`).
 - `pkg/`: reusable public utilities/components (including gateway and helpers).
 - `internal/`: repository-internal implementation details/examples; avoid exposing as public API.
@@ -65,5 +65,5 @@ CI reference is `.github/workflows/lint-test.yml` (lint + gotestsum-based tests)
 - Service lifecycle and management: `core/supervisor/`
 - DI registration patterns: `core/lavabuilder/`
 - HTTP server composition: `servers/https/server.go`
-- gRPC + gateway composition: `servers/gatewayserver/server.go`（`servers/grpcs` 为废弃别名）
+- gRPC + gateway composition: `servers/gatewayserver/server.go`
 - Gateway behavior and routing: `pkg/gateway/`
diff --git a/deploy/traefik/dynamic.yml b/deploy/traefik/dynamic.yml
@@ -14,7 +14,7 @@
 http:
   routers:
     # ---- HTTP/REST + gRPC-Web ----
-    # grpcs 默认把 REST 挂在 /api 前缀（StripPrefix("/api", mux.Handler)）；
+    # gatewayserver 默认把 REST 挂在 /api 前缀（StripPrefix("/api", mux.Handler)）；
     # gRPC-Web 走 /<package>.<service>/<method> 形式的路径。
     gw-http:
       rule: "Host(`api.example.com`)"
@@ -60,7 +60,7 @@ http:
           - url: "h2c://gateway:50051"
 
   # 可选中间件示例：如果后端 REST 不想要 /api 前缀，可在边缘 strip。
-  # 注意：不要和 grpcs 里的 StripPrefix("/api") 重复 strip，二选一。
+  # 注意：不要和 gatewayserver 里的 StripPrefix("/api") 重复 strip，二选一。
   middlewares:
     strip-api:
       stripPrefix:

diff --git a/docs/architecture-v2.md b/docs/architecture-v2.md
@@ -18,7 +18,6 @@ flowchart TD
 
     subgraph Service[服务宿主 servers/*]
         GWS[servers/gatewayserver]
-        GRPCS[servers/grpcs 废弃别名]
         HTTPS[servers/https]
         ZRPCS[servers/zrpcs]
     end
@@ -232,8 +231,6 @@ sequenceDiagram
     Handler-->>Client: 响应
 ```
 
-`servers/grpcs` 是 **废弃别名**，内部调用 `gatewayserver.NewWithName(..., "grpc-server")`。
-
 ### 5.2 zrpc（`servers/zrpcs` + `clients/zrpcc`）
 
 ```mermaid
@@ -341,7 +338,6 @@ lava/
 ├── cmds/                 # CLI 命令
 ├── servers/
 │   ├── gatewayserver/    # ★ 对外多协议网关
-│   ├── grpcs/            # 废弃别名
 │   ├── https/            # 纯 HTTP
 │   └── zrpcs/            # NATS 微服务
 ├── pkg/
@@ -362,7 +358,7 @@ lava/
 
 | 之前 | 现在 |
 | --- | --- |
-| `servers/grpcs` 同时承载网关与 zrpc | `gatewayserver` 纯网关；zrpc 外置 |
+| `servers/grpcs` 包 | 已删除；使用 `gatewayserver` |
 | `Mux.RegisterZrpc` | `pkg/zrpcbridge.RegisterMux`（DI 显式调用） |
 | `grpc_server.zrpc_url` 配置 | 已移除 |
 | 原生 gRPC 空占位 `stream.grpc.go` | 已删除（直接用 `grpc.ServerStream`） |

diff --git a/docs/copilot-skills.md b/docs/copilot-skills.md
@@ -216,7 +216,7 @@ func NewUserConfig() *UserConfig {
 // Create a gRPC service for user management
 // Includes:
 //   - UserService with GetUser and ListUsers methods
-//   - Service registration with grpcs server
+//   - Service registration with gatewayserver
 func NewUserGrpcService() lava.GrpcRouter {
     // Copilot 会生成完整的 gRPC 服务实现
 }

diff --git a/docs/design-v2.md b/docs/design-v2.md
@@ -11,7 +11,7 @@ Lava 在设计上聚焦三件事：
 当前在传输层上，Lava 已覆盖：
 
 - HTTP（`servers/https` / `clients/resty`）
-- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`；`servers/grpcs` 为废弃别名）
+- gRPC Gateway（`servers/gatewayserver` / `pkg/gateway`）
 - zrpc（`servers/zrpcs` / `clients/zrpcc`，protobuf unary over NATS）
 
 ## 2. 核心抽象

diff --git a/docs/legacy-removal.md b/docs/legacy-removal.md
@@ -23,10 +23,15 @@
 
 | 项 | 位置 | 替代方案 |
 |----|------|----------|
-| `servers/grpcs` | 整个包 | `servers/gatewayserver` + `grpc_passthrough: true` |
 | `pkg/wsproxy` 废弃构造函数 | `pkg/wsproxy` | `pkg/gateway` WebSocket 前端 |
 | legacy gRPC 双注册 | `gatewayserver` `grpc_passthrough: false` | 默认 `true`，仅在 Mux 注册 |
 
+### 已移除（v2）
+
+| 项 | 替代方案 |
+|----|----------|
+| `servers/grpcs` 包 | `servers/gatewayserver` + `grpc_passthrough: true` |
+
 ### 配置键
 
 | Legacy 键 | 替代键 |
@@ -66,6 +71,6 @@ gateway_server:
 - [x] HTTP 中间件链统一到 `servers/serverhttp.HandlerMiddleware`（#107）
 - [x] `internal/configs/components/grpc_server.yaml` 已移除，统一 `gateway_server.yaml`
 - [x] `lavabuilder grpc` 通过 `gatewayserver.LoadConfig` 加载 YAML 并对 `grpc_server` 打废弃警告
-- [ ] 架构文档仅描述 `gateway_server`
+- [x] 架构文档仅描述 `gateway_server`
 - [ ] `task test` 不依赖 legacy 路径（或单独 `task test:legacy`）
-- [ ] v3 里程碑前开 PR 删除 `grpcs` 包
+- [x] 删除 `grpcs` 包（v2，不再等待 v3）
diff --git a/docs/modules/servers.md b/docs/modules/servers.md
@@ -7,7 +7,6 @@
 | 模块 | 说明 | 关键入口 |
 | --- | --- | --- |
 | `servers/gatewayserver` | 对外 Gateway：HTTP/REST、gRPC-Web、WebSocket、原生 gRPC | `gatewayserver.New` |
-| `servers/grpcs` | **已废弃别名**，等同 `gatewayserver`（supervisor 名仍为 `grpc-server`） | `grpcs.New` |
 | `servers/https` | Fiber HTTP 服务，默认接入 debug 与基础中间件 | `https.New` |
 | `servers/zrpcs` | zrpc 服务宿主，基于 NATS 托管 protobuf unary/streaming RPC | `zrpcs.New` |
 
@@ -19,28 +18,30 @@
 
 | 协议 | 默认端口 | 配置项 | 实现 |
 | --- | --- | --- | --- |
-| HTTP/REST + gRPC-Web | 8080 | `grpc_server.http_port` / `running.HttpPort` | Fiber，`/api` 前缀 |
-| WebSocket | 8081（可选） | `websocket_port` | `net/http` |
-| 原生 gRPC | 50051 | `grpc_server.grpc_port` / `running.GrpcPort` | `grpc.Server` 或 passthrough |
+| HTTP/REST + gRPC-Web | 8080 | `gateway_server.http` / `running.HttpPort` | Fiber，`/api` 前缀 |
+| WebSocket | 8081（可选） | `gateway_server.websocket_port` | `net/http` |
+| 原生 gRPC | 50051 | `gateway_server.grpc` / `running.GrpcPort` | `grpc.Server` 或 passthrough |
 
 ### 装配流程
 
 1. 收集 `GrpcRouter` / `GrpcHttpRouter` → 注册到 `gateway.Mux`
 2. Fiber 挂 `/api` → `mux.Handler`
-3. 可选 `WebSocketPort` → 独立 `http.Server`
-4. gRPC：legacy 双注册，或 `grpc_passthrough` 仅在 Mux 注册
+3. 可选 `websocket_port` → 独立 `http.Server`
+4. gRPC：默认 `grpc_passthrough: true`（仅在 Mux 注册）；`false` 为 legacy 双注册
 5. 全局中间件：serviceinfo / metric / accesslog / recovery
 6. `vars.Register` 路由信息（`gateway-server-info`，兼容 `grpc-server-info`）
 
 ### 配置
 
-YAML 键：`gateway_server`（推荐）或 legacy `grpc_server`。
+YAML 键：**`gateway_server`**（见 `internal/configs/components/gateway_server.yaml`）。
+
+旧键 `grpc_server` 仍可解析，启动时会打废弃警告；详见 `docs/legacy-removal.md`。
 
 ```yaml
 gateway_server:
   enable_print_router: true
+  grpc_passthrough: true
   websocket_port: 8081
-  grpc_passthrough: false
   http: {}
   grpc: {}
 ```
@@ -52,12 +53,7 @@ gateway_server:
 
 ### 命令入口
 
-`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New`
-
-## `servers/grpcs`（废弃）
-
-类型别名 + `New()` 包装，supervisor 服务名仍为 `grpc-server`，便于老项目兼容。
-新代码请使用 `gatewayserver.New`。
+`lava grpc` → `cmds/grpcservercmd` → `gatewayserver.New` + `gatewayserver.LoadConfig`
 
 ## `servers/https` 要点
 
@@ -113,3 +109,13 @@ flowchart LR
     Bridge[pkg/zrpcbridge] -.->|可选| Mux
     Bridge -.-> NATS
 ```
+
+## Legacy（v3 移除）
+
+| 项 | 替代 |
+| --- | --- |
+| YAML 键 `grpc_server` | `gateway_server` |
+| `grpc_passthrough: false` | 默认 `true` |
+| `servers/grpcs` 包 | 已在 v2 删除，请用 `servers/gatewayserver` |
+
+详见 `docs/legacy-removal.md`。
diff --git a/servers/grpcs/doc.go b/servers/grpcs/doc.go
diff --git a/servers/grpcs/server.go b/servers/grpcs/server.go