# 星线账户技术概览

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

## 服务组成与身份边界

服务端使用 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 会话分别有独立用途和生命周期。

| 模块 | 可确认的职责 | 源码入口 |
| --- | --- | --- |
| 注册、验证码与密码 | 邮箱注册、手机号注册、登录、重置与风险追加验证 | `identity/server/auth.ts` |
| 会话 | Cookie 令牌摘要、来源与受众隔离、凭据版本、撤销 | `identity/server/sessions.ts` |
| 通行密钥与外部身份 | WebAuthn，微信、QQ、支付宝及小程序身份关联 | `identity/server/passkeys.ts`、`identity/server/providers.ts` |
| 资料与认证 | 名称、规范化头像、个人及企业实名认证申请 | `identity/server/profile.ts`、`identity/server/real-name.ts` |
| 管理与审计 | 角色、应用管理、安全事件、管理员操作保护 | `identity/server/admin.ts`、`identity/server/audit.ts` |
| 授权协议 | OIDC 授权码、同意记录与服务端签名接口 | `identity/server/oidc.ts`、`identity/server/open-api.ts` |

## 注册与登录状态

邮箱注册从 `/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 接口。接入步骤与失败处理见[账户接口接入](https://document.thestarline.cn/account/integration.md)。