pikasTech-HWLAB/docs/plan/v02-multi-user-migration.md

v0.2 多用户访问迁移计划

本文记录 v0.2 当前源码状态、与目标用户和权限管理规格的差距，以及推荐迁移路径。长期目标和稳定判定标准以 ../reference/spec-user-access.md 为准。

当前态

从 v0.2 源码看，当前系统还没有真正的多用户访问控制：

• docs/reference/spec-user-access.md 已定义 admin/user、session owner 和 device pod grant 的目标规格，但还没有对应实现。
• internal/db/migrations/0001_cloud_core_skeleton.sql 已有 projects、gateway_sessions、hardware_operations、audit_events、agent_sessions、worker_sessions、agent_trace_events、evidence_records 和 migration ledger；没有 users、user_sessions、device_pods、device_pod_grants、device_leases，agent_sessions 也没有 owner_user_id。
• internal/db/runtime-store.mjs 支持 memory/postgres runtime store 和 readiness，但主要服务 L1 硬件 runtime 数据；用户身份和授权尚未进入 runtime store。
• web/hwlab-cloud-web/auth.mjs 是轻量登录前端，默认 admin/hwlab2026，并有 local session fallback；它不是正式用户体系。
• internal/dev-entrypoint/cloud-web-routes.mjs 仍把 POST /v1/agent/chat、POST /v1/agent/chat/cancel、GET /v1/agent/chat/result/*、GET /v1/agent/chat/trace/* 视为 public proxy route，多用户下必须收敛为 auth-required。
• internal/cloud/code-agent-session-registry.mjs 以内存 Map 维护 session/conversation/facts，没有 owner、用户 session、Postgres 持久归属或跨 Pod 恢复。
• internal/cloud/server.mjs 的 /v1/device-pods 只是代理 hwlab-device-pod 或回退 fake payload，没有按 actor 过滤，也没有 profile authority、POST job 或 lease 权限入口。
• cmd/hwlab-device-pod/main.mjs 和 internal/device-pod/fake-data.mjs 当前只提供 fake GET 数据，不连接真实硬件，也不持久化 device pod 管理数据。
• tools/device-pod-cli.mjs 当前从 code agent workspace 的 .device-pod/ 读取 profile，并直接调用 /v1/rpc/hardware.invoke.shell；正式多用户接入后，本地 profile 不能继续作为 gateway/resource/workspace 的权威来源。
• G14 当前集群里 hwlab-dev 有 hwlab-g14-postgres 和 PVC；hwlab-v02 namespace 还未成为独立运行面。v0.2 权限数据不能混用 hwlab-dev pgdata。

目标差距

领域	当前态	目标态
用户	前端默认账号和本地 session fallback	Postgres users + user_sessions，admin/user 两角色
Code Agent session	内存 ownerless registry	agent_sessions.owner_user_id 持久归属，result/trace/cancel 按 owner 校验
Device Pod	fake GET 数据，所有人可见；CLI 本地 profile 可决定 route	device_pods.profile_json/profile_hash 服务端权威 + device_pod_grants 授权过滤
Device 操作	还不是正式 job/lease 权限入口	cloud-api 授权后转发到 device-pod，独占操作用 device_leases
Cloud Web 路由	部分 agent route public	除 health/static/login 外，用户态 API 都 auth-required
微服务	没有用户服务	不新增用户服务，cloud-api 内置 user/auth/access 模块
v0.2 数据面	namespace/Postgres 目标未落地	hwlab-v02 独立 namespace + 独立 Postgres DB/PVC/Secret

迁移原则

• 不做 group/project/capability/read-operate 分级迁移；直接收敛到 admin/user 和 grant-exists-is-full-access。
• 不新增 user-management 微服务；先把用户管理做成 cloud-api 内部模块和 admin API。
• 不把 audit_events 复用成用户审计；保留它作为既有硬件证据链数据。
• 不把普通用户映射成 Kubernetes user/namespace/RBAC。
• 不为了兼容旧 public route 长期保留双路径；不兼容变更在同一阶段同步改后端、前端和测试。
• v0.2 数据面不复用 hwlab-dev pgdata；如需导入历史数据，显式写一次性迁移脚本并记录来源和目标。

推荐实施阶段

阶段 1：Schema 和 bootstrap admin

新增 0002_multi_user_access_v1 迁移：

• 新增 users、user_sessions、device_pods、device_pod_grants、device_leases。
• 扩展现有 agent_sessions：owner_user_id、conversation_id、thread_id、last_trace_id、session_json、updated_at。
• 写入 bootstrap admin，密码只存 hash。
• 为 fake/default device-pod-71-freq 写入一条 device_pods 记录，并由 admin 导入 server-side profile_json/profile_hash，便于前端从 fake 数据迁到 DB 管理数据。

不兼容处理：已有 ownerless agent_sessions 不继续作为普通用户 session。迁移时一次性归属 bootstrap admin 或标记 expired，迁移后新 session 必须有 owner。

阶段 2：cloud-api auth/access 模块

在 cloud-api 内新增模块：

• authenticateRequest(request)：从 cookie/session token 解析 actor。
• requireActor(request)：未登录返回 401。
• requireAdmin(actor)：非 admin 返回 403。
• authorizeAgentSession(actor, sessionId|traceId|conversationId)：admin 或 owner。
• authorizeDevicePod(actor, devicePodId)：admin 或存在 device_pod_grants。

不兼容处理：除 /health、/health/live、静态资源和登录接口外，用户态 /v1/* 不再允许匿名访问。旧 public code agent poll route 直接改为 auth-required，不保留 legacy public mode。

阶段 3：Cloud Web 登录和 admin UI

调整 cloud-web：

• /auth/session、/auth/login、/auth/logout 代理或落到 cloud-api authority。
• 移除多用户运行态下的 local auth fallback；没有 server session 时显示登录页。
• 增加最小 admin UI：用户列表、创建/禁用用户、device pod 授权/撤销。
• 普通用户只显示自己的 code agent session 和被授权 device pod。

不兼容处理：默认 admin/hwlab2026 只能作为 bootstrap 初始化入口；完成初始化后应由管理员改密码或替换。前端测试 fixture 同步改成 server-session 模式。

阶段 4：Code Agent session owner 持久化

调整 /v1/agent/chat 及相关路由：

• 创建或复用 session 时写入 agent_sessions.owner_user_id。
• conversation_id -> session_id 绑定迁到 Postgres 或至少写入 session record。
• result/trace/cancel/inspect 根据 owner 校验。
• code agent prompt 中只暴露当前 actor 可见的 device pod 列表。

不兼容处理：部署前存在的浏览器本地 conversation/session 可能失效；前端应在 401/403/session_expired 时提示重新登录或新建会话，不做 ownerless session 兼容恢复。

阶段 5：Device Pod 管理和授权过滤

调整 /v1/device-pods：

• list/status 从 device_pods 读取管理数据，再按 actor 过滤。
• admin 可创建/更新/禁用 device pod。
• admin 是 profile authority，只能通过 cloud-api 创建/更新 device_pods.profile_json。
• admin 可 upsert/delete device_pod_grants。
• 未授权用户访问具体 device pod 返回 403。

不兼容处理：普通用户不再默认看到 device-pod-71-freq。如果需要演示用户看到它，必须显式给该用户授权。code agent 本地 .device-pod/*.json 不再能改变正式 device pod route。

阶段 6：Device jobs 和 lease

为真实设备操作增加 cloud-api job routes：

• POST /v1/device-pods/{devicePodId}/jobs
• GET /v1/device-pods/{devicePodId}/jobs/{jobId}
• POST /v1/device-pods/{devicePodId}/jobs/{jobId}/cancel

cloud-api 先校验 actor 和 grant，再按操作类型获取 device_leases，最后转发到 hwlab-device-pod 内部 Service。

不兼容处理：device-pod 服务不面向普通用户直接暴露，不接受浏览器或 worker 直连作为授权依据，也不接受调用方上传 profile 作为执行依据；所有真实操作必须经过 cloud-api。

阶段 7：v0.2 namespace 和数据面

部署面调整：

• 创建 hwlab-v02 namespace。
• 建立 v0.2 独立 Postgres StatefulSet、Service、PVC 和 DB Secret。
• cloud-api v0.2 指向 v0.2 DB URL 和独立 migration ledger。
• Cloud Web/API FRP 使用 v0.2 规划入口 19666/19667。

不兼容处理：不把 hwlab-dev 数据自动复制到 v0.2。需要保留的数据必须写明迁移对象、来源、目标和回滚方式；用户权限数据默认从 bootstrap admin 开始重建。

其他微服务调整

微服务	必要调整
hwlab-cloud-api	新增 user/auth/access 模块、admin API、session owner 校验、device grant/lease 校验。
hwlab-cloud-web	登录改为 server-session authority；增加 admin UI；普通用户视图按授权过滤。
hwlab-edge-proxy	保持透明转发，确保 cookie/header 不被丢弃；不注入业务 actor。
hwlab-agent-mgr	session 创建参数和状态摘要带 owner_user_id、session_id label；不自行做最终授权。
hwlab-agent-worker	Pod/Job/PVC label 带 owner/session，工具调用 device pod 时走 cloud-api。
hwlab-device-pod	从 fake GET 逐步扩展到多 devicePodId jobs API；信任 cloud-api 内部调用，不保存用户 grant，不接受用户上传 profile。
hwlab-agent-skills	device-pod-cli 默认目标改为 cloud-api 授权 REST 入口，不直连 device-pod Service，不再以本地 profile 作为正式 route authority。
GitOps/render	v0.2 增加 namespace、Postgres、SecretRef、ServiceAccount、PVC 和 env 注入。

最小验证

• 未登录访问 /v1/agent/chat/result/*、/v1/agent/chat/trace/* 和 /v1/device-pods 返回 401。
• admin 能创建用户、创建设备、授权和撤销授权。
• 未授权 user 看不到 device pod，访问具体 device pod 返回 403。
• 授权后 user 能看到并使用 device pod。
• user A 不能读取或取消 user B 的 code agent session。
• admin 可以跨用户查看和取消 session。
• 同一个 device pod 的独占操作只能被一个 active lease 持有。
• v0.2 cloud-api health 报告连接的是 v0.2 DB，不是 hwlab-dev pgdata。