星线账户技术概览

星线账户（Account）负责账户凭据、网页登录、安全设置、个人资料和应用授权。资料依据 2026 年 10 月 23 日 identity/ 源码整理。账户站为 https://account.thestarline.cn，第三方接入见开放平台，微信小程序确认见星线智联。

服务组成与身份边界

服务端使用 Node.js、TypeScript、Fastify 和 MySQL。identity/server/main.ts 组装注册登录、协议、开放 API、静态前端与投递工作器；identity/server/app.ts 负责请求上下文、来源校验、CSRF、路由限额及统一错误。前端在 identity/client/，账户站与开放平台按配置的站点来源识别，不通过任意请求参数切换管理权限。

账户主键是 32 位十六进制字符串。它与聊天服务的用户 UUID、好友码、企业组织 ID 都是不同标识。业务系统应通过授权响应建立自己的映射，不把邮箱或手机号码当作永不变化的主键，也不解析显示名称推断身份。Account Cookie、OIDC 令牌、开放 API 签名密钥、聊天 Bearer 会话分别有独立用途和生命周期。

注册与登录状态

邮箱注册从 /api/register/start 开始，经历邮箱验证码、手机号验证和密码设置后，才能调用 /api/register/complete。中间步骤依赖服务端 transactionId 与当前浏览器上下文；收到一次验证码成功响应并不等于整个账户已经注册。手机号注册使用 /api/register/phone/start，验证手机号后完成注册，首次完成可以签发账户 Cookie；重复完成不会再创建新会话。手机号注册后的账户可以再添加其他凭据。

密码登录与邮箱、手机验证码登录都进入统一风险判断。邮箱验证码、手机验证码和风险验证码发送接口当前均校验 CAPTCHA。邮箱投递使用持久化任务；request_accepted 表示请求已受理，不能用来证明目标存在、邮件已送达或用户已登录。风险追加验证响应需要客户端继续执行相应事务，不能提前显示登录成功。

默认账户会话有效期为 28,800 秒，即 8 小时；验证码有效期 300 秒，通用注册事务 1,800 秒，验证码最多尝试 5 次、重发间隔 60 秒。具体协议还可能使用更短的挑战或授权期限。会话认证同时检查令牌摘要、到期、撤销、来源、受众、账户封禁和凭据版本，不以客户端保存了 Cookie 为有效依据。

安全设置与资料数据

安全设置提供当前会话、安全事件、登录验证策略、凭据管理及会话撤销。修改密码、绑定联系方式或撤销会话等操作通常先获取短时、单次的重新验证授权 grantId。授权绑定当前上下文；更换浏览器、凭据改变或重复使用都会失效。普通用户的单方式验证具有资格检查和期限，拥有管理权限的账户不能据此绕过管理员要求。

管理角色包含 platform_admin、account_admin、auditor。管理员登录方式是否强制为通行密钥，当前由 IDENTITY_ADMIN_PASSKEY_REQUIRED 是否精确等于 true 决定，不能把生产环境自动等同于强制启用。管理角色也不等于星企的企业所有者或管理员。

资料名称先做 NFC 规范化与首尾清理，最多 32 个 Unicode 字符，拒绝控制和双向文本控制字符。头像仅接受静态 JPG、PNG，解码前原文件不超过 256 KiB、像素总数不超过 1,048,576；服务端重新编码为 512×512 JPEG，清除原图 EXIF、GPS 等元数据。账户头像读取是当前用户私有接口，不是公开头像托管服务。

实名功能有独立开关和人工审核状态。材料格式、文件大小、身份资料加密与审核权限由服务端校验，上传申请不等于通过认证。授权给第三方的 verification 声明只提供状态、类型及获批企业名称等摘要，不向第三方下发个人证件材料。

存储、配置与运行条件

当前 MySQL 存储按 001.sql 至 007.sql 执行基础迁移，再处理 PII 与资料等兼容迁移。IDENTITY_DATABASE_URL 必需；生产还要求独立的 IDENTITY_PII_KEY。联系方式以 AES-256-GCM 加密，并用带用途区分的 HMAC 建立检索值，不能用普通哈希替代可控的联系方式查询设计。密钥标记不匹配时拒绝启动。旧明文迁移要求已核验备份后显式批准；迁移器本身不创建备份。

IDENTITY_SECRET、PII 密钥、OIDC 签名密钥有不同用途，恢复资料必须包含数据库与对应密钥的安全托管记录。只恢复数据库、临时重新生成密钥或删掉版本标记不能构成可用恢复方案。生产 OIDC 需要稳定 JWKS 文件；受信代理需要显式地址列表，不接受通配信任。

邮件生产投递走腾讯云 SES，短信走阿里云短信；SMTP 只供非生产使用。手机号校验和实际短信目标当前限制在中国大陆 +86 手机号码，界面的地区选项不能证明已支持全球短信。实际部署配置与真实投递需分别验收。

验证与已知边界

仓库提供 identity/tests/auth.test.ts、profile.test.ts、pii.test.ts、oidc-profile.test.ts 等测试，可通过 identity/package.json 的 test、typecheck、build 脚本检查。真实短信、邮件、第三方回调、管理权限与浏览器保持仍需受控环境验证。历史回执仅对应其记录的版本、时间与范围。

账户密码变化会影响 Account 自身凭据版本和相关授权，但不会自动撤销独立聊天服务已签发的会话。原生产品退出时还要区分本机清理和服务端撤销是否成功。当前 Account 实现未提供记忆转出 redeem 接口。接入步骤与失败处理见账户接口接入。