feat: simplify local administrator login

.env.docker.example

@@ -7,8 +7,10 @@ FRONTEND_PORT=3010
 API_PORT=8031
 PUBLIC_URL=http://localhost:8031
 
-# Required. The installers generate all four values automatically.
+# API transport token is required for non-localhost binds and Fleet/Agent/API
+# integrations. The installer generates it automatically.
 API_AUTH_TOKEN=
+# Optional legacy emergency/OIDC bootstrap token; local login does not use it.
 BOOTSTRAP_ADMIN_TOKEN=
 SECRET_KEY=
 CREDENTIAL_ENCRYPTION_KEY=

README.md

@@ -55,12 +55,13 @@ Invoke-WebRequest https://raw.githubusercontent.com/2233admin/opencli-Razormind/
 | API 文档 | http://localhost:8031/docs | REST API 与集成调试 |
 | 内置浏览器 | http://localhost:6080 | 扫码或登录需要账号的平台 |
 
-安装完成后，终端会打印：
+安装完成后可以直接使用本地管理员账号登录：
 
-- `BOOTSTRAP_ADMIN_TOKEN`：首次进入管理界面使用；
-- `API_AUTH_TOKEN`：Fleet、Agent、API 和 MCP 访问使用。
+- 用户名：`admin`
+- 密码：`admin`
+- 登录后可在「账户设置」修改密码
 
-两者同时保存在安装目录的 `.env`。不要公开 noVNC、令牌或浏览器调试端口；远程部署建议使用 HTTPS、反向代理或 SSH 隧道。
+`API_AUTH_TOKEN` 仅由 Fleet、Agent、API 和 MCP 传输使用，自动保存在安装目录的 `.env`，不需要填入管理界面。不要公开 API 令牌、noVNC 或浏览器调试端口；远程部署建议使用 HTTPS、反向代理或 SSH 隧道。
 
 ## 正常的研究流程
 

backend/api/v1/identity.py

@@ -1,15 +1,70 @@
-"""Request identity endpoint."""
+"""Local administrator and request identity endpoints."""
 
 from typing import Annotated
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field
 
+from backend.config import get_settings
 from backend.schemas.common import ApiResponse
 from backend.security.identity import RequestIdentity, get_request_identity
+from backend.security.local_auth import (
+    hash_password,
+    issue_local_token,
+    persist_password_hash,
+    verify_password,
+)
+
+
+class LocalLoginRequest(BaseModel):
+    username: str = Field(min_length=1, max_length=255)
+    password: str = Field(min_length=1, max_length=255)
+
+
+class ChangePasswordRequest(BaseModel):
+    current_password: str = Field(min_length=1, max_length=255)
+    new_password: str = Field(min_length=6, max_length=255)
+
 
 router = APIRouter(prefix="/auth", tags=["auth"])
 
 
+@router.post("/login", response_model=ApiResponse[dict])
+async def local_login(body: LocalLoginRequest) -> ApiResponse:
+    settings = get_settings()
+    if body.username != settings.local_admin_username or not verify_password(
+        body.password, settings.local_admin_password_hash
+    ):
+        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "用户名或密码错误")
+
+    return ApiResponse.ok(
+        {
+            "access_token": issue_local_token(settings.local_admin_username, settings.secret_key),
+            "token_type": "bearer",
+            "using_default_password": verify_password(
+                "admin", settings.local_admin_password_hash
+            ),
+        }
+    )
+
+
+@router.post("/password", response_model=ApiResponse[dict])
+async def change_local_password(
+    body: ChangePasswordRequest,
+    identity: Annotated[RequestIdentity, Depends(get_request_identity)],
+) -> ApiResponse:
+    if identity.auth_method != "local":
+        raise HTTPException(status.HTTP_403_FORBIDDEN, "仅本地管理员可以修改本地密码")
+    settings = get_settings()
+    if not verify_password(body.current_password, settings.local_admin_password_hash):
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "当前密码错误")
+    if body.new_password == body.current_password:
+        raise HTTPException(status.HTTP_400_BAD_REQUEST, "新密码不能与当前密码相同")
+    persist_password_hash(hash_password(body.new_password))
+    get_settings.cache_clear()
+    return ApiResponse.ok({"message": "密码已更新"})
+
+
 @router.get("/me", response_model=ApiResponse[dict])
 async def read_identity(
     identity: Annotated[RequestIdentity, Depends(get_request_identity)],

backend/api/v1/workspaces.py

@@ -3,7 +3,7 @@
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend.database import get_db
-from backend.models.identity import User, Workspace, WorkspaceMembership, WorkspaceRole
+from backend.models.identity import Team, User, Workspace, WorkspaceMembership, WorkspaceRole
 from backend.models.workflow import Project
 from backend.schemas.common import ApiResponse
 from backend.schemas.workflow_asset import ProjectRead
@@ -54,6 +54,51 @@ async def _get_or_create_user(
         raise HTTPException(status.HTTP_409_CONFLICT, "Disabled user cannot join a Workspace")
     return user
 
+async def _ensure_local_admin_workspace(
+    db: AsyncSession,
+    identity: RequestIdentity,
+) -> None:
+    if identity.auth_method != "local":
+        return
+
+    user = await db.scalar(select(User).where(User.subject == identity.subject))
+    if user is None:
+        user = User(
+            subject=identity.subject,
+            display_name=identity.name or "本地管理员",
+        )
+        db.add(user)
+        await db.flush()
+
+    workspace = await db.scalar(select(Workspace).where(Workspace.slug == "opencli-default"))
+    if workspace is None:
+        workspace = Workspace(name="OpenCLI 工作区", slug="opencli-default")
+        db.add(workspace)
+        await db.flush()
+
+    membership = await db.scalar(
+        select(WorkspaceMembership)
+        .where(WorkspaceMembership.workspace_id == workspace.id)
+        .where(WorkspaceMembership.user_id == user.id)
+    )
+    if membership is None:
+        db.add(
+            WorkspaceMembership(
+                workspace_id=workspace.id,
+                user_id=user.id,
+                role=WorkspaceRole.ADMIN,
+            )
+        )
+
+    team = await db.scalar(
+        select(Team)
+        .where(Team.workspace_id == workspace.id)
+        .where(Team.slug == "default")
+    )
+    if team is None:
+        db.add(Team(workspace_id=workspace.id, name="默认团队", slug="default"))
+        await db.flush()
+
 
 @router.get(
     "/governance/workspaces",
@@ -63,6 +108,7 @@ async def list_accessible_workspaces(
     identity: RequestIdentity = Depends(get_request_identity),
     db: AsyncSession = Depends(get_db),
 ) -> ApiResponse:
+    await _ensure_local_admin_workspace(db, identity)
     rows = (
         (
             await db.execute(

backend/config.py

@@ -3,6 +3,8 @@
 
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from backend.security.local_auth import DEFAULT_LOCAL_ADMIN_PASSWORD_HASH
+
 
 class Settings(BaseSettings):
     model_config = SettingsConfigDict(
@@ -59,6 +61,11 @@ class Settings(BaseSettings):
     # guard only allows on a localhost bind. Env: API_AUTH_TOKEN.
     api_auth_token: str = ""
 
+    # Local-first account used by the NAS/server deployment. The password hash
+    # is persisted in .env after the user changes the default password.
+    local_admin_username: str = "admin"
+    local_admin_password_hash: str = DEFAULT_LOCAL_ADMIN_PASSWORD_HASH
+
     # CLI channel binary allowlist (ADR-0005, audit P0-4). The cli channel is
     # an arbitrary-binary-execution surface, so it only runs binaries the
     # operator explicitly listed here. Comma-separated binary paths/names,

backend/security/fleet_auth.py

@@ -67,6 +67,7 @@
 from collections.abc import Sequence
 from urllib.parse import parse_qs
 
+from jose import JWTError, jwt
 from starlette.datastructures import Headers
 from starlette.responses import JSONResponse
 from starlette.types import ASGIApp, Receive, Scope, Send
@@ -77,6 +78,10 @@
 #: Path prefixes guarded by :class:`FleetAuthMiddleware`.
 PROTECTED_PREFIXES = ("/api", "/mcp")
 
+# Local login is intentionally the only unauthenticated API route. Once the
+# user has a local bearer session, the identity dependency authenticates it.
+PUBLIC_PATHS = frozenset({"/api/v1/auth/login"})
+
 _LOCALHOST_HOSTS = frozenset({"localhost", "::1"})
 
 
@@ -120,6 +125,17 @@ def enforce_bind_guard(host: str, token: str) -> None:
         "local development."
     )
 
+def _is_local_session(credential: str) -> bool:
+    try:
+        claims = jwt.decode(
+            credential,
+            get_settings().secret_key,
+            algorithms=["HS256"],
+        )
+    except JWTError:
+        return False
+    return claims.get("auth_method") == "local" and claims.get("sub") == "local-admin"
+
 
 def _token_matches(candidate: str, token: str) -> bool:
     """Constant-time comparison of a caller-supplied credential against *token*."""
@@ -147,30 +163,34 @@ class FleetAuthMiddleware:
     /health exemption rationale.
     """
 
+
     def __init__(self, app: ASGIApp) -> None:
         self.app = app
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if scope["type"] not in ("http", "websocket") or not scope["path"].startswith(
-            PROTECTED_PREFIXES
+        if (
+            scope["type"] not in ("http", "websocket")
+            or not scope["path"].startswith(PROTECTED_PREFIXES)
+            or scope["path"] in PUBLIC_PATHS
         ):
             await self.app(scope, receive, send)
             return
 
-        # Read per request: get_settings() is lru_cached (cheap), but
-        # api/v1/system.py may cache_clear() it at runtime after a config
-        # patch, so don't freeze the token at middleware construction time.
+        # Read per request so a runtime configuration update is respected.
         token = get_settings().api_auth_token
         if not token:
-            # Dev posture: no token configured -> API open. Only reachable on
-            # a localhost bind thanks to enforce_bind_guard at startup.
+            # No fleet token configured: local deployments rely on the identity
+            # dependency and the bind guard limits this posture to localhost.
             await self.app(scope, receive, send)
             return
 
         if scope["type"] == "websocket":
             headers = Headers(scope=scope)
-            credential = _bearer_credential(headers) or _query_token(scope.get("query_string", b""))
-            if credential and _token_matches(credential, token):
+            bearer = _bearer_credential(headers)
+            credential = bearer or _query_token(scope.get("query_string", b""))
+            if _is_local_session(bearer) or (
+                credential and _token_matches(credential, token)
+            ):
                 await self.app(scope, receive, send)
                 return
             await WebSocketClose(code=4401, reason="Invalid or missing API token")(
@@ -179,8 +199,9 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
             return
 
         headers = Headers(scope=scope)
-        credential = headers.get("x-api-token", "") or _bearer_credential(headers)
-        if credential and _token_matches(credential, token):
+        bearer = _bearer_credential(headers)
+        credential = headers.get("x-api-token", "") or bearer
+        if _is_local_session(bearer) or (credential and _token_matches(credential, token)):
             await self.app(scope, receive, send)
             return
 

backend/security/identity.py

@@ -19,14 +19,18 @@ class IdentitySettings:
     audience: str
     jwks_url: str = ""
     bootstrap_admin_token: str = ""
+    secret_key: str = "change-me-in-production"
 
     @classmethod
     def from_env(cls) -> IdentitySettings:
+        from backend.config import get_settings
+
         return cls(
             issuer=os.getenv("OIDC_ISSUER", "").rstrip("/"),
             audience=os.getenv("OIDC_AUDIENCE", ""),
             jwks_url=os.getenv("OIDC_JWKS_URL", ""),
             bootstrap_admin_token=os.getenv("BOOTSTRAP_ADMIN_TOKEN", ""),
+            secret_key=get_settings().secret_key,
         )
 
 
@@ -129,6 +133,18 @@ async def get_request_identity(request: Request) -> RequestIdentity:
                 "Bearer token required",
                 headers={"WWW-Authenticate": "Bearer"},
             )
+        try:
+            local_claims = jwt.decode(token, resolved.secret_key, algorithms=["HS256"])
+        except JWTError:
+            local_claims = None
+        if local_claims and local_claims.get("auth_method") == "local":
+            return RequestIdentity(
+                subject="local-admin",
+                name=local_claims.get("name") or "本地管理员",
+                username=local_claims.get("username"),
+                is_platform_admin=True,
+                auth_method="local",
+            )
         if resolved.bootstrap_admin_token and hmac.compare_digest(
             token, resolved.bootstrap_admin_token
         ):