chore: commit pending agent/controller updates and docs

Runbook/Fix-Agent-404-And-UUID-Change.md

@@ -435,7 +435,10 @@ export GCP_REGION=asia-northeast1
 # 4. 构建镜像（如果使用 Makefile）
 make cloudrun-build
 
-# 5. 部署服务
+# 5. 更新 service.yaml 以使用 Secret Manager
+# 确保 service.yaml 中 INTERNAL_SERVICE_TOKEN 使用 valueFrom: secretKeyRef 配置
+
+# 6. 部署服务
 make cloudrun-deploy
 
 # 或者使用 gcloud 命令

cmd/accountsvc/main.go

@@ -848,9 +848,7 @@ func runServer(ctx context.Context, cfg *config.Config, logger *slog.Logger) err
 
 	api.RegisterRoutes(r, options...)
 
-	if agentRegistry != nil {
-		registerAgentAPIRoutes(r, agentRegistry, gormSource, logger)
-	}
+	registerAgentAPIRoutes(r, agentRegistry, gormSource, logger)
 
 	addr := strings.TrimSpace(cfg.Server.Addr)
 	if addr == "" {
@@ -1059,9 +1057,8 @@ func runAgent(ctx context.Context, cfg *config.Config, logger *slog.Logger) erro
 const agentIdentityContextKey = "xcontrol-account-agent-identity"
 
 func registerAgentAPIRoutes(r *gin.Engine, registry *agentserver.Registry, source xrayconfig.ClientSource, logger *slog.Logger) {
-	if registry == nil {
-		return
-	}
+	// Canonical agent controller path. Keep this route registered even when registry is nil
+	// so callers receive explicit auth/config errors instead of 404.
 	// Use /api/agent-server/v1 to avoid conflict with /api/agent prefix used by admin/user API
 	group := r.Group("/api/agent-server/v1")
 	group.Use(agentAuthMiddleware(registry))

deploy/gcp/cloud-run/service.yaml

@@ -49,6 +49,11 @@ spec:
           value: postgres
         - name: DB_NAME
           value: account
+        - name: INTERNAL_SERVICE_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: internal-service-token
+              key: latest
         # --- SMTP Configuration ---
         - name: SMTP_HOST
           value: "smtp.qq.com"

docs/api/overview.md

@@ -9,7 +9,7 @@
 
 - 健康检查：`GET /healthz`
 - 用户 API：`/api/auth/*`
-- Agent API：`/api/agent/v1/*`
+- Agent API：`/api/agent-server/v1/*`
 
 ## 认证方式
 

docs/architecture/overview.md

@@ -9,7 +9,7 @@ Client
   └─ HTTP API (Gin)
        ├─ Session / MFA / Email verification
        ├─ Subscription & Admin Settings
-       ├─ Agent Controller (/api/agent/v1)
+       ├─ Agent Controller (/api/agent-server/v1)
        └─ Token Service (optional)
            │
            ├─ Store (memory / postgres)

docs/getting-started/concepts.md

@@ -41,7 +41,7 @@
 
 ## Agent / Xray 同步
 
-- Controller（账号服务）暴露 `/api/agent/v1` 接口
+- Controller（账号服务）暴露 `/api/agent-server/v1` 接口
 - Agent 定时拉取用户列表生成 Xray 配置
 - Agent 上报健康状态供管理员查看
 

internal/agentmode/client.go

@@ -84,7 +84,7 @@ func NewClient(baseURL, token string, opts ClientOptions) (*Client, error) {
 
 // ListClients fetches the current set of Xray clients from the controller.
 func (c *Client) ListClients(ctx context.Context) (agentproto.ClientListResponse, error) {
-	endpoint, err := url.JoinPath(c.baseURL.String(), "/api/agent/v1/users")
+	endpoint, err := url.JoinPath(c.baseURL.String(), "/api/agent-server/v1/users")
 	if err != nil {
 		return agentproto.ClientListResponse{}, err
 	}
@@ -115,7 +115,7 @@ func (c *Client) ListClients(ctx context.Context) (agentproto.ClientListResponse
 
 // ReportStatus submits the agent status report to the controller.
 func (c *Client) ReportStatus(ctx context.Context, report agentproto.StatusReport) error {
-	endpoint, err := url.JoinPath(c.baseURL.String(), "/api/agent/v1/status")
+	endpoint, err := url.JoinPath(c.baseURL.String(), "/api/agent-server/v1/status")
 	if err != nil {
 		return err
 	}