feat: bootstrap console administrator

2026-09-21 05:13:47 +08:00
parent 6af20c2cd4
commit 6a25a718c4
5 changed files with 147 additions and 10 deletions
--- a/cmd/orbit-admin/main.go
+++ b/cmd/orbit-admin/main.go
@@ -258,6 +258,11 @@ func runBootstrap(args []string) error {
 	flags.StringVar(&in.Environment, "environment", "", "environment name")
 	flags.StringVar(&in.Queue, "queue", "", "initial queue name")
 	flags.StringVar(&output, "output", "", "new private credentials JSON file")
+	var consoleUsername, consoleDisplayName, consolePassword string
+	var consolePasswordStdin bool
+	flags.StringVar(&consoleUsername, "console-username", "", "optional first console administrator username")
+	flags.StringVar(&consoleDisplayName, "console-display-name", "", "optional console administrator display name")
+	flags.BoolVar(&consolePasswordStdin, "console-password-stdin", false, "read the first console administrator password from stdin")
 	flags.BoolVar(&in.WorkerAccess, "worker-access", false, "also grant Worker connect and consume actions for development")
 	flags.BoolVar(&in.ScheduleAccess, "schedule-access", false, "also grant schedule read and manage actions for development")
 	flags.BoolVar(&in.EventAccess, "event-access", false, "also grant result subscription read, manage and consume actions")
@@ -274,6 +279,20 @@ func runBootstrap(args []string) error {
 	if flags.NArg() != 0 || output == "" {
 		return errors.New("--output and named resource arguments are required")
 	}
+	if consolePasswordStdin {
+		raw, err := io.ReadAll(io.LimitReader(os.Stdin, 1025))
+		if err != nil {
+			return errors.New("console administrator password could not be read")
+		}
+		consolePassword = strings.TrimRight(string(raw), "\r\n")
+	}
+	if consoleUsername == "" && (consolePasswordStdin || consoleDisplayName != "") {
+		return errors.New("--console-username is required with console administrator options")
+	}
+	if consoleUsername != "" && !consolePasswordStdin {
+		return errors.New("--console-password-stdin is required when creating the first console administrator")
+	}
+	in.ConsoleUsername, in.ConsoleDisplayName, in.ConsolePassword = consoleUsername, consoleDisplayName, consolePassword
 	cfg, err := config.Load()
 	if err != nil {
 		return err
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -21,6 +21,23 @@ ORBIT_MYSQL_DSN 通过环境注入，命令不读取 .env。所有名称必填

 输出 JSON 包含 application_id / namespace_id / queue_id / credential_id / token / expires_at。初始凭据有效期为 30 天，权限包括当前命名空间内的五个 P1 动作和全部队列。初始队列 max_concurrency=4、rate_per_second=10、max_unfinished_tasks=100000；并发、开始限速与积压背压已生效，语义及管理方式见 [队列接口](queues.md)。这些默认值是开发基线，不是容量承诺。

+如果希望在第一次初始化时同时创建控制台管理员，可在同一条 bootstrap 事务中提供账号，并从标准输入交付密码：
+
+```sh
+secret-manager read orbit/console-admin-password | \
+  go run ./cmd/orbit-admin bootstrap \
+    --application sample-app \
+    --namespace default \
+    --environment production \
+    --queue files \
+    --console-username admin \
+    --console-display-name 'Orbit 管理员' \
+    --console-password-stdin \
+    --output .local/production.credentials.json
+```
+
+`--console-password-stdin` 要求密码至少 12 个字节，密码不会出现在命令参数、日志或交付 JSON 中。业务凭据、控制台账号和两条初始化审计会在同一个数据库事务中提交；任何一步失败都会整体回滚。交付 JSON 只会额外包含 `console_username`，后续新增控制台账号仍使用 [`orbit-admin console-user create`](../console.md)。
+
 资源、凭据摘要和初始化审计在一个事务中提交。交付文件先写入并同步到磁盘，成功后再提交事务。如果文件写入失败则回滚并移除文件；如果已经交付后提交无法确认，保留文件并报错，应使用其中凭据核对结果，不能直接覆盖或重复创建。

 初始文件包含真实秘密，应保管在受限目录或导入秘密管理系统。运行账户与迁移/初始化账户分开；生产只通过 HTTPS 使用凭据。
--- a/docs/console.md
+++ b/docs/console.md
@@ -32,7 +32,22 @@ http://127.0.0.1:8080/console/
 http://127.0.0.1:8080/console/
 ```

-首次使用需要由数据库管理员创建一个控制台账号。账号绑定一个已有的命名空间凭据，账号权限就是该凭据的权限；这不会轮换或输出业务 Token。推荐从私有凭据文件读取命名空间和凭据标识，并从标准输入交付密码：
+首次使用可以在 `orbit-admin bootstrap` 时一起创建控制台管理员。这样业务资源、业务凭据和管理员账号在同一个初始化事务中提交：
+
+```sh
+secret-manager read orbit/console-admin-password | \
+  ./bin/orbit-admin bootstrap \
+    --application sample-app \
+    --namespace default \
+    --environment production \
+    --queue files \
+    --console-username admin \
+    --console-display-name 'Orbit 管理员' \
+    --console-password-stdin \
+    --output .local/production.credentials.json
+```
+
+密码不会进入命令参数、日志或 JSON 文件，初始化失败时资源和账号一起回滚。已经完成业务初始化的环境，也可以由数据库管理员单独创建控制台账号。账号绑定一个已有的命名空间凭据，账号权限就是该凭据的权限；这不会轮换或输出业务 Token。推荐从私有凭据文件读取命名空间和凭据标识，并从标准输入交付密码：

 ```sh
 ./bin/orbit-admin console-user create \
@@ -44,7 +59,11 @@ http://127.0.0.1:8080/console/

 命令会把密码写成 bcrypt 哈希，只输出账号的脱敏信息。生产环境应通过受保护的密钥管道提供标准输入；不要把密码写进命令历史、镜像或仓库。账号创建后直接打开控制台，用账号密码登录。

-`ORBIT_CONSOLE_QUEUE_ID` 只作为单一默认队列的展示和查询范围配置，页面不再要求填写 API 地址、队列 ID、Bearer Token，也不再选择凭据 JSON：
+页面的 API 地址默认自动取当前访问地址的 origin，不需要手填。部署到域名后，直接访问 `https://orbit.example.com/console/`，页面会自动请求同一域名下的服务端接口；生产建议用反向代理让控制台和 API 保持同源。页面不再要求填写队列 ID、Bearer Token，也不再选择凭据 JSON。
+
+如果未来把前端静态资源和服务端拆成不同域名，需要额外设计 API 基地址、CORS、Cookie `SameSite`/Domain 和 CSRF 防护，不能只替换一个 URL。当前内置控制台优先保证同源部署的安全边界。
+
+`ORBIT_CONSOLE_QUEUE_ID` 只作为单一默认队列的展示和查询范围配置：

 ```sh
 export ORBIT_CONSOLE_QUEUE_ID='queue_xxx'
--- a/internal/storage/mysql/bootstrap.go
+++ b/internal/storage/mysql/bootstrap.go
@@ -5,11 +5,13 @@ import (
 	"database/sql"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"time"

 	core "git.yuntuo.hk/k2safe/orbit/model"
 	"git.yuntuo.hk/k2safe/orbit/platform/auth"
 	"git.yuntuo.hk/k2safe/orbit/pulse/service"
+	"golang.org/x/crypto/bcrypt"
 )

 // BootstrapInput 仅供持有数据库管理权限的初始化命令使用，不暴露为公共 HTTP。
@@ -30,16 +32,20 @@ type BootstrapInput struct {
 	ScheduleAccess         bool    // ScheduleAccess 显式增加开发用计划查询及管理权限。
 	ResourceAccess         bool    // ResourceAccess 显式授予整个应用的额度查询及管理权限。
 	ExistingApplicationID  core.ID // ExistingApplicationID 在指定现有应用下创建命名空间，与 Application 二选一。
+	ConsoleUsername        string  // ConsoleUsername 可选的首个控制台管理员用户名；与 ConsolePassword 成对使用。
+	ConsoleDisplayName     string  // ConsoleDisplayName 可选的控制台展示名称，空时使用用户名。
+	ConsolePassword        string  // ConsolePassword 仅在初始化事务内短暂使用，数据库只保存 bcrypt 哈希。
 }

 // BootstrapResult 包含一次性交付的原始凭据，禁止记录到日志或提交到版本库。
 type BootstrapResult struct {
-	ApplicationID core.ID   `json:"application_id"` // ApplicationID 创建或关联的应用标识。
-	NamespaceID   core.ID   `json:"namespace_id"`   // NamespaceID 新建隔离范围。
-	QueueID       core.ID   `json:"queue_id"`       // QueueID 初始队列标识。
-	CredentialID  core.ID   `json:"credential_id"`  // CredentialID 凭据记录标识。
-	Token         string    `json:"token"`          // Token 原始秘密，仅保存到受保护交付文件。
-	ExpiresAt     time.Time `json:"expires_at"`     // ExpiresAt 初始凭据到期时间，UTC。
+	ApplicationID   core.ID   `json:"application_id"`             // ApplicationID 创建或关联的应用标识。
+	NamespaceID     core.ID   `json:"namespace_id"`               // NamespaceID 新建隔离范围。
+	QueueID         core.ID   `json:"queue_id"`                   // QueueID 初始队列标识。
+	CredentialID    core.ID   `json:"credential_id"`              // CredentialID 凭据记录标识。
+	Token           string    `json:"token"`                      // Token 原始秘密，仅保存到受保护交付文件。
+	ExpiresAt       time.Time `json:"expires_at"`                 // ExpiresAt 初始凭据到期时间，UTC。
+	ConsoleUsername string    `json:"console_username,omitempty"` // ConsoleUsername 可选的首个控制台账号，不包含密码。
 }

 func Bootstrap(ctx context.Context, db *sql.DB, in BootstrapInput, deliver func(BootstrapResult) error) error {
@@ -54,6 +60,9 @@ func Bootstrap(ctx context.Context, db *sql.DB, in BootstrapInput, deliver func(
 	if !service.ValidName(in.Environment, 32) || deliver == nil {
 		return fmt.Errorf("environment and secure delivery are required")
 	}
+	if (in.ConsoleUsername == "") != (in.ConsolePassword == "") || (in.ConsoleUsername == "" && in.ConsoleDisplayName != "") {
+		return fmt.Errorf("console username and password must be provided together")
+	}
 	if err := CheckSchema(ctx, db); err != nil {
 		return err
 	}
@@ -73,6 +82,11 @@ func Bootstrap(ctx context.Context, db *sql.DB, in BootstrapInput, deliver func(
 		}
 		*dest = v
 	}
+	if in.ConsoleUsername != "" {
+		if err := validateConsoleUserInput(ConsoleUserInput{NamespaceID: out.NamespaceID, CredentialID: out.CredentialID, Username: in.ConsoleUsername, DisplayName: in.ConsoleDisplayName, Password: in.ConsolePassword}); err != nil {
+			return err
+		}
+	}
 	secret, digest, err := auth.Issue(out.NamespaceID, out.CredentialID)
 	if err != nil {
 		return err
@@ -118,6 +132,19 @@ func Bootstrap(ctx context.Context, db *sql.DB, in BootstrapInput, deliver func(
 	if err := permissions.Validate(); err != nil {
 		return err
 	}
+	var consolePasswordHash []byte
+	var consoleUserID core.ID
+	if in.ConsoleUsername != "" {
+		consolePasswordHash, err = bcrypt.GenerateFromPassword([]byte(in.ConsolePassword), consolePasswordCost)
+		if err != nil {
+			return err
+		}
+		consoleUserID, err = core.NewID()
+		if err != nil {
+			return err
+		}
+		out.ConsoleUsername = in.ConsoleUsername
+	}
 	raw, err := json.Marshal(permissions)
 	if err != nil {
 		return err
@@ -150,17 +177,37 @@ func Bootstrap(ctx context.Context, db *sql.DB, in BootstrapInput, deliver func(
 		if _, err = tx.ExecContext(ctx, "INSERT INTO orbit_credentials(namespace_id,id,name,secret_digest,permissions,expires_at) VALUES (?,?,'bootstrap',?,?,?)", out.NamespaceID, out.CredentialID, digest, string(raw), out.ExpiresAt); err != nil {
 			return err
 		}
-		op, err := core.NewID()
+		actor, err := databaseActor(ctx, tx)
 		if err != nil {
 			return err
 		}
-		actor, err := databaseActor(ctx, tx)
+		op, err := core.NewID()
 		if err != nil {
 			return err
 		}
 		if err := appendAuditActor(ctx, tx, out.NamespaceID, actor, op, "bootstrap.create", out.CredentialID, "database administrator bootstrap", nil, map[string]any{"permissions": permissions, "expires_at": out.ExpiresAt}); err != nil {
 			return err
 		}
+		if in.ConsoleUsername != "" {
+			name := strings.TrimSpace(in.ConsoleDisplayName)
+			if name == "" {
+				name = in.ConsoleUsername
+			}
+			if _, err := tx.ExecContext(ctx, `INSERT INTO orbit_console_users
+				(id,namespace_id,credential_id,username,display_name,password_hash)
+				VALUES (?,?,?,?,?,?)`, consoleUserID, out.NamespaceID, out.CredentialID, in.ConsoleUsername, name, string(consolePasswordHash)); err != nil {
+				return err
+			}
+			consoleOperationID, err := core.NewID()
+			if err != nil {
+				return err
+			}
+			if err := appendAuditActor(ctx, tx, out.NamespaceID, actor, consoleOperationID, "console_user.create", consoleUserID, "bootstrap console administrator", nil, map[string]any{
+				"username": in.ConsoleUsername, "display_name": name, "credential_id": out.CredentialID,
+			}); err != nil {
+				return err
+			}
+		}
 		// 交付文件先持久化再提交；提交失败时保留文件以便核对不确定结果。
 		return deliver(out)
 	})
--- a/internal/storage/mysql/bootstrap_test.go
+++ b/internal/storage/mysql/bootstrap_test.go
@@ -0,0 +1,35 @@
+package mysql
+
+import (
+	"context"
+	"strings"
+	"testing"
+)
+
+func TestBootstrapConsoleAdministratorRequiresUsernameAndPassword(t *testing.T) {
+	base := BootstrapInput{Application: "app", Namespace: "default", Environment: "test", Queue: "queue"}
+	for name, in := range map[string]BootstrapInput{
+		"username without password": func() BootstrapInput {
+			in := base
+			in.ConsoleUsername = "admin"
+			return in
+		}(),
+		"password without username": func() BootstrapInput {
+			in := base
+			in.ConsolePassword = "a sufficiently long password"
+			return in
+		}(),
+		"display name without account": func() BootstrapInput {
+			in := base
+			in.ConsoleDisplayName = "Orbit 管理员"
+			return in
+		}(),
+	} {
+		t.Run(name, func(t *testing.T) {
+			err := Bootstrap(context.Background(), nil, in, func(BootstrapResult) error { return nil })
+			if err == nil || !strings.Contains(err.Error(), "console username and password") {
+				t.Fatalf("expected console administrator validation error, got %v", err)
+			}
+		})
+	}
+}