Help us shape the future of Go! Take the 2026 Go Developer Survey

api

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2026 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package api 是 fleetly 控制面 v0.1 API 服务实现与拦截器链（T2.17； 架构 D21：proto 唯一真源，鉴权/限流在 gRPC 拦截器链）。

鉴权模型（architecture §4.2 安全基线）：Authorization: Bearer <token> → tokens 表哈希比对（常量时间二次校验）→ scope 判定（read ⊂ deploy ⊂ admin，方法级映射在本包 scope.go）——**无 token / 错 token 全部 401**， scope 不足 403。错误码取舍：401/403 无专用稳定码，用信封退化形态 （code 空 + grpc code 机械映射 HTTP），与 FZ-2 口径一致（本阶段 internal/errcode 不在允许改动清单，不加码）。

Index

Constants

View Source 
const (
	ScopeRead   = "read"
	ScopeDeploy = "deploy"
	ScopeAdmin  = "admin"
)

scope 词表（state-model §2.9 / architecture §4.2：read/deploy/admin）。

Variables

This section is empty.

Functions

func GenerateBootstrapAdminToken 

func GenerateBootstrapAdminToken(ctx context.Context, st *state.Store, note string) (string, error)

GenerateBootstrapAdminToken 生成并落库 admin token（T2.17 安装引导； 明文返回一次，库内只存哈希）。审计 ActorTokenID 空 = 自举（无调用方 token）。已存在任意 token 时调用方应跳过（HasAnyToken 谓词）。

func RequiredScope 

func RequiredScope(fullMethod string) (string, bool)

RequiredScope 返回方法所需 scope（未登记返回 false——调用方按 admin 拒绝路径处理）。

Types

type AppsService 

type AppsService struct {
	serverv1.UnimplementedAppsServiceServer
	// contains filtered or unexported fields
}

AppsService 实现 server.v1.AppsService（T2.17）：列表带派生状态、详情 带 placement 与最近部署、删除走 tombstone 生命周期（state 现有状态机）。 T2.19 增补 webhook/git 触发配置面（SetAppWebhookSecret/ShowAppWebhook/ SetAppSource——secret 与认证材料经平台 envelope 加密落库，明文不落、 永不回读；show 面只回 configured 位）。

func NewAppsService 

func NewAppsService(st *state.Store, box *secrets.Box, gitEndpoint string, withdraw RouteWithdrawer) *AppsService

NewAppsService 构造 AppsService（box 为 webhook secret 加密器； gitEndpoint 供 git remote 提示；withdraw 为路由撤销端口，可 nil）。

func (*AppsService) DeleteApp 

func (s *AppsService) DeleteApp(ctx context.Context, req *serverv1.DeleteAppRequest) (*serverv1.DeleteAppResponse, error)

DeleteApp 推进 active → deleting（tombstone 第一拍）：保留期内名字仍 占用、不复活；与审计同事务 fail-closed。actor 记调用方 token（审计 action = api.AppsService.DeleteApp，方法级；不发明新事件）。 H9：deleting 第一拍提交后同步撤销路由（域名台账清理 + 全量重发布， 空视图落 noop 兜底——Traefik 侧真实撤销旧路由而非 502 残留）。

func (*AppsService) GetApp 

func (s *AppsService) GetApp(ctx context.Context, req *serverv1.GetAppRequest) (*serverv1.GetAppResponse, error)

GetApp 应用详情：placement / 最近部署 / 派生状态正交细节。

func (*AppsService) ListApps 

func (s *AppsService) ListApps(ctx context.Context, req *serverv1.ListAppsRequest) (*serverv1.ListAppsResponse, error)

ListApps 列出应用（active + deleting；deleted tombstone 不进默认列表 ——GetApp 可显式查看，列表面向运营主视图）。派生状态批量化（S18-A4）： limit 截断后的 app 集合经 state 层两次 IN 查询（PlacementByApp + LatestDeploymentsByApp）取全部派生输入，替代逐 app 的 GetPlacement + ListAppDeployments N+1 形态。

func (*AppsService) SetAppSource 

func (s *AppsService) SetAppSource(ctx context.Context, req *serverv1.SetAppSourceRequest) (*serverv1.SetAppSourceResponse, error)

SetAppSource 设置拉源配置（admin；T2.19）：url + branch + 认证形态。 整体替换语义（每次调用写全量字段）；认证材料必须与 auth_kind 同调提供 ——材料经 envelope 加密落库，读回面无明文，因此无法「留旧」。

func (*AppsService) SetAppWebhookSecret 

func (s *AppsService) SetAppWebhookSecret(ctx context.Context, req *serverv1.SetAppWebhookSecretRequest) (*serverv1.SetAppWebhookSecretResponse, error)

SetAppWebhookSecret 设置 per-app webhook 签名密钥（admin；T2.19）：值经 平台 envelope 加密落库（明文不落），审计 app.webhook_secret_set 在 state 层同事务 fail-closed。secret 缺失的端点是 404 语义（未配置即未启用）。

func (*AppsService) ShowAppWebhook 

func (s *AppsService) ShowAppWebhook(ctx context.Context, req *serverv1.ShowAppWebhookRequest) (*serverv1.ShowAppWebhookResponse, error)

ShowAppWebhook 回读 webhook/git 触发配置（无敏感投影；admin）。

type Authenticator 

type Authenticator struct {
	// contains filtered or unexported fields
}

Authenticator 是 token 认证器（state 层哈希认证 + last_used_at 节流盖写 + scope 判定 + per-token 限流——限流在认证成功后判定，身份先于限流成立）。

func NewAuthenticator 

func NewAuthenticator(st *state.Store) *Authenticator

NewAuthenticator 构造认证器（内置缺省参数限流器：宽松防滥用）。

func (*Authenticator) Authenticate 

func (a *Authenticator) Authenticate(ctx context.Context, authorization string) (Principal, error)

Authenticate 校验 Bearer 凭据并返回身份；失败返回 grpc status（401/403 信封退化形态）。required scope 判定在 authorize（拦截器按方法映射调用）。 认证成功后经 A2 节流盖写 last_used_at（窗口内只写一次）。

func (*Authenticator) StreamAuthInterceptor 

func (a *Authenticator) StreamAuthInterceptor() grpc.StreamServerInterceptor

StreamAuthInterceptor 流式鉴权拦截器（Follow/Watch 双流同矩阵）。

func (*Authenticator) UnaryAuthInterceptor 

func (a *Authenticator) UnaryAuthInterceptor() grpc.UnaryServerInterceptor

UnaryAuthInterceptor 一元鉴权拦截器（链位：最外层，先于限流与 protovalidate）。

type BuildsService 

type BuildsService struct {
	serverv1.UnimplementedBuildsServiceServer
	// contains filtered or unexported fields
}

BuildsService 实现 server.v1.BuildsService（T2.18）。TriggerBuild 与 Deploy 同型契约：compose 内容字节入队前受控子集校验（compose 违约不动 底座、不入队），构建目标裁决（railpack/dockerfile + image 直通）在服务 端——旧 CLI 直连入库时在客户端做的 selectBuildTargets 随 CLI-over-SDK 改造收编到服务端，目标裁决单一事实源随行。builds.request 跨进程执行 契约不变（daemon 的 build.queue worker 消费同一 JSON 形态）。

S18-A11：服务持 build.Queue，入队走 Queue.Enqueue（建行 + 唤醒）—— 同进程触发立即唤醒扫描（不等 poll interval），Queue.Enqueue 自死代码 转正；queue 为 nil（进程内夹具形态）时回落直连建行，行为与旧路径一致。

func NewBuildsService 

func NewBuildsService(st *state.Store, queue *build.Queue) *BuildsService

NewBuildsService 构造 BuildsService（queue 可 nil——未接队列面的进程内 夹具形态，入队回落直连建行）。

func (*BuildsService) GetBuild 

func (s *BuildsService) GetBuild(ctx context.Context, req *serverv1.GetBuildRequest) (*serverv1.GetBuildResponse, error)

GetBuild 单条构建（CLI build 的等待轮询源）。

func (*BuildsService) ListBuilds 

func (s *BuildsService) ListBuilds(ctx context.Context, req *serverv1.ListBuildsRequest) (*serverv1.ListBuildsResponse, error)

ListBuilds 按应用列构建（created_at 倒序）。

func (*BuildsService) TriggerBuild 

func (s *BuildsService) TriggerBuild(ctx context.Context, req *serverv1.TriggerBuildRequest) (*serverv1.TriggerBuildResponse, error)

TriggerBuild 解析 compose、裁决构建目标并逐服务入队（应用不存在时自动 创建——构建常是应用的第一个平台动作，与 deploy 同语义）。

type DeploymentsService 

type DeploymentsService struct {
	serverv1.UnimplementedDeploymentsServiceServer
	// contains filtered or unexported fields
}

DeploymentsService 实现 server.v1.DeploymentsService（T2.17）。

Deploy 契约（proto 取舍注记）：compose 内容字节 + app 名入队，返回 deployment id 后立即返回；终态由客户端轮询 GetDeployment 或消费事件流。 compose 落临时文件后走受控子集校验（compose.Load）；A7（S18）起入队时 字节持久化 <数据根>/deployments/<id>/compose.yaml 并以该路径随行落库 ——引擎 preparing 阶段重载复核不再依赖 OS 临时目录（tmpfiles 清理/容器 形态丢失免疫），终态后由 janitor 按 30 天窗清理；temp 仅解析中转。

func NewDeploymentsService 

func NewDeploymentsService(st *state.Store, git GitDeployTriggers) *DeploymentsService

NewDeploymentsService 构造 DeploymentsService（git 触发端口可 nil—— DeployFromGit 届时显式不可用，进程内夹具形态）。

func (*DeploymentsService) CancelDeployment 

func (s *DeploymentsService) CancelDeployment(ctx context.Context, req *serverv1.CancelDeploymentRequest) (*serverv1.CancelDeploymentResponse, error)

CancelDeployment 置位取消（受限语义：未切流可取消；曾健康/终态 409 ——引擎侧二次校验为权威）。

func (*DeploymentsService) Deploy 

func (s *DeploymentsService) Deploy(ctx context.Context, req *serverv1.DeployRequest) (*serverv1.DeployResponse, error)

Deploy 入队部署（同 CLI：入队前受控子集校验——compose 违约不动底座、 不入队；deployment.queued 事件与审计同事务 fail-closed）。校验期警告随 响应带出（T2.18：CLI 改经 RPC 入队后保留警告的人读呈现）。

func (*DeploymentsService) DeployFromGit 

func (s *DeploymentsService) DeployFromGit(ctx context.Context, req *serverv1.DeployFromGitRequest) (*serverv1.DeployFromGitResponse, error)

DeployFromGit 是 git push(SSH) 触发入口的入队面（T2.19）：post-receive 钩子经 loopback REST 携带 hook token（deploy scope）调用。compose 字节 由服务端从 bare 仓库自取（真源在 git 对象库，不信任客户端传字节）；sha 为 40 位 commit（protovalidate 形状 + 服务端十六进制复核）。审计在源端 实现（git.push_deploy，actor=system + 钩子 token id）。

func (*DeploymentsService) GetDeployment 

func (s *DeploymentsService) GetDeployment(ctx context.Context, req *serverv1.GetDeploymentRequest) (*serverv1.GetDeploymentResponse, error)

GetDeployment 单条部署。

func (*DeploymentsService) ListDeployments 

func (s *DeploymentsService) ListDeployments(ctx context.Context, req *serverv1.ListDeploymentsRequest) (*serverv1.ListDeploymentsResponse, error)

ListDeployments 按应用列部署（created_at 倒序）。

func (*DeploymentsService) RollbackDeployment 

func (s *DeploymentsService) RollbackDeployment(ctx context.Context, req *serverv1.RollbackDeploymentRequest) (*serverv1.RollbackDeploymentResponse, error)

RollbackDeployment 回滚入队（engine.EnqueueRollback：目标解析失败 E_ROLLBACK_NO_TARGET；事件/审计在引擎入队路径内置）。

type DomainsService 

type DomainsService struct {
	serverv1.UnimplementedDomainsServiceServer
	// contains filtered or unexported fields
}

DomainsService 实现 server.v1.DomainsService。

func NewDomainsService 

func NewDomainsService(st *state.Store, mgr *ingress.Manager) *DomainsService

NewDomainsService 构造 DomainsService。

func (*DomainsService) ListAppDomains 

func (s *DomainsService) ListAppDomains(ctx context.Context, req *serverv1.ListAppDomainsRequest) (*serverv1.ListAppDomainsResponse, error)

ListAppDomains 域名台账（只读；写入方唯一 = internal/ingress 发布对账）。

func (*DomainsService) VerifyAppDomains 

func (s *DomainsService) VerifyAppDomains(ctx context.Context, req *serverv1.VerifyAppDomainsRequest) (*serverv1.VerifyAppDomainsResponse, error)

VerifyAppDomains 本机视角域名验证（ingress.VerifyDomains；探测材料 如实记录，判断权在操作者）。

type DriftService 

type DriftService struct {
	serverv1.UnimplementedDriftServiceServer
	// contains filtered or unexported fields
}

DriftService 实现 server.v1.DriftService（T2.18）：漂移判定/收敛/opt-in 置位复用 engine 既有逻辑（DriftShow/ConvergeApp/SetDriftConverge），本面 只做契约投影——不重写对账语义。actor 恒 "human"（API 无法区分人类/AI 代理，可追溯性由审计 actor_token_id 承载，与 rollback 面同口径）。

func NewDriftService 

func NewDriftService(st *state.Store, eng *engine.Engine) *DriftService

NewDriftService 构造 DriftService。

func (*DriftService) ConvergeDrift 

func (s *DriftService) ConvergeDrift(ctx context.Context, req *serverv1.ConvergeDriftRequest) (*serverv1.ConvergeDriftResponse, error)

ConvergeDrift 人工一次性收敛（归位重放原语，带审计；在途部署存在时 409 语义由引擎承载）。

func (*DriftService) SetDriftConverge 

func (s *DriftService) SetDriftConverge(ctx context.Context, req *serverv1.SetDriftConvergeRequest) (*serverv1.SetDriftConvergeResponse, error)

SetDriftConverge 收敛 opt-in 的人工置位/重置（回滚失败强制关闭后的 唯一恢复入口；带审计）。

func (*DriftService) ShowDrift 

func (s *DriftService) ShowDrift(ctx context.Context, req *serverv1.ShowDriftRequest) (*serverv1.ShowDriftResponse, error)

ShowDrift 即时判定运行域漂移（不写事件不收敛——与 CLI 读面同源）。

type EnvService 

type EnvService struct {
	serverv1.UnimplementedEnvServiceServer
	// contains filtered or unexported fields
}

EnvService 实现 server.v1.EnvService（T2.17）：Set/Remove 走 pending 语义（state 层内置），Get 明文解密（admin scope 在拦截器链强制）， List 恒不出值。值加密边界：入站明文 → box.Encrypt 落库；出站解密仅在 GetEnv 显式路径。

func NewEnvService 

func NewEnvService(st *state.Store, box *secrets.Box) *EnvService

NewEnvService 构造 EnvService。

func (*EnvService) GetEnv 

func (s *EnvService) GetEnv(ctx context.Context, req *serverv1.GetEnvRequest) (*serverv1.GetEnvResponse, error)

GetEnv 读回明文（admin scope 专用路径；密文解密失败按内部错误透出）。

func (*EnvService) ListEnv 

func (s *EnvService) ListEnv(ctx context.Context, req *serverv1.ListEnvRequest) (*serverv1.ListEnvResponse, error)

ListEnv 键名/来源/状态位（值恒脱敏）。

func (*EnvService) RemoveEnv 

func (s *EnvService) RemoveEnv(ctx context.Context, req *serverv1.RemoveEnvRequest) (*serverv1.RemoveEnvResponse, error)

RemoveEnv 删除平台 env（幂等性不做：键不存在 404；台账立即删行，运行 实例 env 快照随下次部署更新）。

func (*EnvService) SetEnv 

func (s *EnvService) SetEnv(ctx context.Context, req *serverv1.SetEnvRequest) (*serverv1.SetEnvResponse, error)

SetEnv 设置平台 env（pending；值密文落库，审计在 state 层 fail-closed）。

func (*EnvService) WithEnvChangedHook 

func (s *EnvService) WithEnvChangedHook(fn func(appID string)) *EnvService

WithEnvChangedHook 注入 env 写路径联动回调（H9 装配点：fleetlyd 接到 logs.Manager.InvalidateRedaction）。回调在写事务提交成功后同步执行， 实现必须非阻塞（实现方只做缓存删除）。

type EventsService 

type EventsService struct {
	serverv1.UnimplementedEventsServiceServer
	// contains filtered or unexported fields
}

EventsService 实现 server.v1.EventsService（T2.17）：Watch 是 seq 游标 server-streaming（architecture §2.3）。实现 = 周期轮询 state.EventsSince （Outbox 行读，事件与业务写同事务落库）：

  • 断线重连：客户端带 since_seq 续读（seq > since_seq 升序）；
  • 游标过期：**流上发一帧 cursor_expired 信封错误帧（带 oldest_seq） 后正常关闭流**（取舍见 events.proto 注释——gateway chunked-JSON 面 中途改状态码不可行，显式断档帧让消费方重新对齐）；
  • 无限流：有界批量（每轮至多 500 条）+ 轮询间隔 1s。

func NewEventsService 

func NewEventsService(st *state.Store) *EventsService

NewEventsService 构造 EventsService。

func (*EventsService) WatchEvents 

func (s *EventsService) WatchEvents(req *serverv1.WatchEventsRequest, stream serverv1.EventsService_WatchEventsServer) error

WatchEvents 实现事件流（入口先过 A5 per-token 并发闸：超限 ResourceExhausted，流结束/ctx 取消时 defer 释放槽位）。

type GitDeployTriggers 

type GitDeployTriggers interface {
	// DeployFromGitPush 以 git push 语义入队部署：每次调用建部署记录
	// （显式用户动作，不去重——幂等口径绑定在票面）；返回记录与校验期
	// 警告。actorTokenID 记录钩子回调 token（可空）。ref 非该 app 配置
	// 分支（空回落 main）时返回 gitserver.ErrBranchNotTracked——分支
	// 过滤的权威点在实现侧（daemon），本 handler 把哨兵映射为 skipped
	// 回执而非 gRPC 错误。
	DeployFromGitPush(ctx context.Context, app, sha, ref, actorTokenID string) (state.DeployRecord, []compose.Warning, error)
}

GitDeployTriggers 是 DeployFromGit RPC 的 git 触发端口（实现方在 internal/gitserver 的 GitTriggers——compose 真源在其 bare 仓库对象库； 方向纪律：api 定义端口、不感知实现类型——唯一例外是跨端口的错误哨兵 契约 gitserver.ErrBranchNotTracked（值依赖，非实现类型依赖）；命名口径 UBIQUITOUS_LANGUAGE §flagged-2：与实现类型同族词汇，弃旧名 GitDeploySource）。

type GitKeysService 

type GitKeysService struct {
	serverv1.UnimplementedGitKeysServiceServer
	// contains filtered or unexported fields
}

GitKeysService 实现 server.v1.GitKeysService（T2.19）：平台管理的 git 公钥（SSH push 认证；v0.1 全局级，admin scope 管理）。公钥指纹入库 （SHA256，ssh-keygen -lf 同格式）；私钥永不经过平台。生命周期动作审计 在 state 层与业务写同事务 fail-closed（gitkey.add / gitkey.remove）。

func NewGitKeysService 

func NewGitKeysService(st *state.Store) *GitKeysService

NewGitKeysService 构造 GitKeysService。

func (*GitKeysService) AddGitKey 

func (s *GitKeysService) AddGitKey(ctx context.Context, req *serverv1.AddGitKeyRequest) (*serverv1.AddGitKeyResponse, error)

AddGitKey 解析 authorized_keys 单行并入库（指纹唯一——重复注册 409 退化 信封）。

func (*GitKeysService) ListGitKeys 

func (s *GitKeysService) ListGitKeys(ctx context.Context, _ *serverv1.ListGitKeysRequest) (*serverv1.ListGitKeysResponse, error)

ListGitKeys 在册公钥列表（公钥为公开材料可回读）。

func (*GitKeysService) RemoveGitKey 

func (s *GitKeysService) RemoveGitKey(ctx context.Context, req *serverv1.RemoveGitKeyRequest) (*serverv1.RemoveGitKeyResponse, error)

RemoveGitKey 删除公钥（幂等语义：不存在 404 退化信封；删除即时生效 ——在推连接不受影响，新握手即拒绝）。

type IngressStatusSource 

type IngressStatusSource interface {
	Status(ctx context.Context) (ingress.Status, error)
	Config() ingress.Config
}

IngressStatusSource 是入口状态消费端口（*ingress.Manager 隐式实现）。

type LogsService 

type LogsService struct {
	serverv1.UnimplementedLogsServiceServer
	// contains filtered or unexported fields
}

LogsService 实现 server.v1.LogsService（T2.20）：Follow 接管线实时面 （ring 回放 + 实时扇出），History 接落盘/构建产物检索。脱敏已在采集端 （internal/logs），本面不二次处理。

func NewLogsService 

func NewLogsService(st *state.Store, mg *logs.Manager) *LogsService

NewLogsService 构造 LogsService。

func (*LogsService) FollowLogs 

func (s *LogsService) FollowLogs(req *serverv1.FollowLogsRequest, stream serverv1.LogsService_FollowLogsServer) error

FollowLogs 实时跟随（server-streaming；ctx 取消即断流，重连 = 重新 Follow）。

func (*LogsService) ListHistoryLogs 

func (s *LogsService) ListHistoryLogs(ctx context.Context, req *serverv1.ListHistoryLogsRequest) (*serverv1.ListHistoryLogsResponse, error)

ListHistoryLogs 历史检索（时间窗/服务/来源过滤）。

type PlacementService 

type PlacementService struct {
	serverv1.UnimplementedPlacementServiceServer
	// contains filtered or unexported fields
}

PlacementService 实现 server.v1.PlacementService。

func NewPlacementService 

func NewPlacementService(st *state.Store) *PlacementService

NewPlacementService 构造 PlacementService。

func (*PlacementService) ShowPlacement 

func (s *PlacementService) ShowPlacement(ctx context.Context, req *serverv1.ShowPlacementRequest) (*serverv1.ShowPlacementResponse, error)

ShowPlacement 放置绑定视图（未绑定时 placement 不输出）+ 卷注册表 （T2.18：卷的钉住语义由放置绑定决定，与绑定同面展示）。

type Principal 

type Principal struct {
	TokenID string
	Scopes  []string
}

Principal 是通过鉴权的调用方身份（handler 侧审计 actor_token_id 消费）。

func PrincipalFromContext 

func PrincipalFromContext(ctx context.Context) (Principal, bool)

PrincipalFromContext 取调用方身份（未鉴权路径不存在——拦截器链强制）。

type RevisionsService 

type RevisionsService struct {
	serverv1.UnimplementedRevisionsServiceServer
	// contains filtered or unexported fields
}

RevisionsService 实现 server.v1.RevisionsService。

func NewRevisionsService 

func NewRevisionsService(st *state.Store) *RevisionsService

NewRevisionsService 构造 RevisionsService。

func (*RevisionsService) GetRevisionSpec 

func (s *RevisionsService) GetRevisionSpec(ctx context.Context, req *serverv1.GetRevisionSpecRequest) (*serverv1.GetRevisionSpecResponse, error)

GetRevisionSpec 单条快照的归一化 compose 正文（canonical JSON；T2.18 plan 的 RPC 基线消费——env 为 key:sha256，值明文结构性不在快照中）。 superseded → 404（与回滚选项面同口径：列不出来的不可消费）。

func (*RevisionsService) ListRevisions 

func (s *RevisionsService) ListRevisions(ctx context.Context, req *serverv1.ListRevisionsRequest) (*serverv1.ListRevisionsResponse, error)

ListRevisions 版本快照列表（保留窗；列表即回滚选项集）。

type RouteWithdrawer 

type RouteWithdrawer interface {
	WithdrawAppRoutes(ctx context.Context, appID string) error
}

RouteWithdrawer 是路由撤销端口（internal/ingress.Manager 隐式实现）： 删该 app 域名台账行 + 全量重发布（空视图落 noop 兜底，旧路由在 Traefik 侧真实撤销）。域名台账写入方唯一 = internal/ingress，故删除清理必须经 此通道而非直写 state。

type SystemComponent 

type SystemComponent struct {
	Name  string
	Check func() error
}

SystemComponent 是带名的健康组件（CheckHealth 复用面）。

type SystemService 

type SystemService struct {
	serverv1.UnimplementedSystemServiceServer
	// contains filtered or unexported fields
}

SystemService 实现 server.v1.SystemService：进程级系统信息（Ping/Status， T0.3/T2.17）+ 集群级观察面（ListNodes/GetIngressStatus，T2.18）。

ingress 依赖以 IngressStatusSource 端口注入（实现 = *ingress.Manager）： 入口探测在服务端执行——CLI 不再直连 docker / 读本地 token 文件 / 探测 配置端点（CLI-over-SDK 单一通道纪律）；nil 端口 = 入口面未装配（测试 形态），Traefik 视图如实报告不可用而非谎报。

func NewSystemService 

func NewSystemService(version string, st *state.Store, components func() []SystemComponent, ing IngressStatusSource) *SystemService

NewSystemService 构造 SystemService（version 由构建 -ldflags 注入； components 为装配点命名的健康组件集；ing 可为 nil——入口面未装配形态）。

func (*SystemService) GetIngressStatus 

func (s *SystemService) GetIngressStatus(ctx context.Context, req *serverv1.GetIngressStatusRequest) (*serverv1.GetIngressStatusResponse, error)

GetIngressStatus 入口链三面状态（T2.18）：① Traefik 服务实况（Swarm inspect，不可达如实标注）；② 配置端点两面探测（/healthz 无鉴权 + /configs 带 token 鉴权核验——环回执行，401 = token 缺失/错误，如实报告）； ③ 证书台账（domains 表 cert 列）与证书存储目录对照。

func (*SystemService) GetSystemStatus 

func (s *SystemService) GetSystemStatus(ctx context.Context, req *serverv1.GetSystemStatusRequest) (*serverv1.GetSystemStatusResponse, error)

GetSystemStatus 健康汇总（引擎/Traefik/状态层/备份——复用 CheckHealth 面）： 逐组件如实上报，不聚合单一布尔，判断权在消费方。备份明细（最近一次 台账行的时间与 verify_status）随 backup 字段带出——组件布尔之外让 「备份上次何时成功」直接可见（T2.22 状态诚实契约）。

func (*SystemService) ListBackups 

func (s *SystemService) ListBackups(ctx context.Context, req *serverv1.ListBackupsRequest) (*serverv1.ListBackupsResponse, error)

ListBackups 状态备份台账只读列表（T2.22；n 缺省 50——台账量级受保留 份数约束，50 已覆盖全部现行行 + 近期失败行）。

func (*SystemService) ListNodes 

func (s *SystemService) ListNodes(ctx context.Context, req *serverv1.ListNodesRequest) (*serverv1.ListNodesResponse, error)

ListNodes 节点观测缓存只读列表（state-model §2.2：缓存禁止用于决策， 展示/诊断专用；节点变更用 docker node 原生命令）。

func (*SystemService) Ping 

func (s *SystemService) Ping(ctx context.Context, req *serverv1.PingRequest) (*serverv1.PingResponse, error)

Ping 回应 service / version。proto 字段上的 buf.validate 最小约束由拦截 器统一校验；Ping 豁免鉴权（T2.17 契约：与 healthz 同为存活面）。

func (*SystemService) TriggerBackup 

func (s *SystemService) TriggerBackup(ctx context.Context, req *serverv1.TriggerBackupRequest) (*serverv1.TriggerBackupResponse, error)

TriggerBackup 手动触发一次状态备份（同步：响应即落账后的台账行； verify_status=failed 时以 FailedPrecondition 返回且台账行保留失败事实 ——调用方看得见失败，绝不渲染成成功）。

func (*SystemService) WithBackupManager 

func (s *SystemService) WithBackupManager(m *statebackup.Manager) *SystemService

WithBackupManager 注入状态备份管理器（T2.22；链式装配，nil 合法—— 测试/精简形态的备份面缺省）。

type TokensService 

type TokensService struct {
	serverv1.UnimplementedTokensServiceServer
	// contains filtered or unexported fields
}

TokensService 实现 server.v1.TokensService（T2.17；state-model §2.9）。 哈希存储：明文只在 CreateToken 响应出现一次；List 只出备注/scope/ 哈希前缀。scope 集（admin 蕴含 deploy 蕴含 read）在 containsScope 判定。

func NewTokensService 

func NewTokensService(st *state.Store) *TokensService

NewTokensService 构造 TokensService。

func (*TokensService) CreateToken 

func (s *TokensService) CreateToken(ctx context.Context, req *serverv1.CreateTokenRequest) (*serverv1.CreateTokenResponse, error)

CreateToken 生成并落库新 token：明文仅本次响应可见。

func (*TokensService) ListTokens 

func (s *TokensService) ListTokens(ctx context.Context, _ *serverv1.ListTokensRequest) (*serverv1.ListTokensResponse, error)

ListTokens 在册 token 列表（无敏感投影；完整哈希与明文永不回读）。

func (*TokensService) RevokeToken 

func (s *TokensService) RevokeToken(ctx context.Context, req *serverv1.RevokeTokenRequest) (*serverv1.RevokeTokenResponse, error)

RevokeToken 吊销（幂等；不存在 404）。M4-6 最后管理员守卫：吊销后平台 必须仍存在 ≥1 枚未吊销 admin token——依次吊销全部 admin 会使平台锁死 （重启也不补种 bootstrap：HasAnyToken 已见 token 行，一次性语义），最后 一枚的吊销被守卫拒绝（E_TOKEN_LAST_ADMIN 409，提示先创建新 token）。 守卫判定与吊销在 state 层同一事务内闭合（RevokeTokenGuardLastAdmin）。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.