# disk.zone

> disk.zone 是一个面向开发者的云存储平台：KV 键值存储、SQL 数据库、FS 文件存储三项产品（即将上线），加上统一的账号、余额与充值，以及供 *.disk.zone 子项目和第三方网站使用的单点登录（同域 SSO、OAuth 2.0 / OpenID Connect）。

账号即用户 ID：4–32 位小写字母、数字、_ 或 -，注册后不变；密码至少 6 位。登录后在个人空间使用各产品、查看余额与流水、通过 iDataRiver 充值、管理登录设备、API Key 与已授权应用。所有 *.disk.zone 子项目共用同一套账号与余额。

公开 API：https://disk.zone/api（JSON 索引）与 https://disk.zone/api/openapi.json（OpenAPI 3.1）。响应统一为 {"ok":true,"data":…} 或 {"ok":false,"error":{"code":"snake_case","message":"中文说明",…}}。余额以 micro 整数精确记账（1 = 1,000,000 micros）。金额字段成组返回：x（货币单位的数字）、x_micros（整数）、x_text（格式化文本，如 $1.50）。时间为 Unix 毫秒。认证方式：浏览器 Cookie（登录时 mode=cookie）、Authorization: Bearer <access_token>（mode=token，15 分钟，refresh_token 续期）、Authorization: Bearer dzk.<username>.<keyid>.<secret>（API Key）。

## 产品

- [KV 键值存储](https://disk.zone/kv): 按命名空间组织的键值存储（即将上线，目前可了解介绍）
- [SQL 数据库](https://disk.zone/sql): 托管的 SQL 数据库（即将上线）
- [FS 文件存储](https://disk.zone/fs): 以根目录组织的文件存储（即将上线）
- [个人空间](https://disk.zone/app): 登录后进入；左侧切换 KV / SQL / FS，第二栏是命名空间、数据库或根目录列表（当前为预览数据）

## 账号与余额

- [注册与登录](https://disk.zone/app): 未登录访问个人空间会弹出登录面板；登录状态在 *.disk.zone 各子项目间共享
- [账户](https://disk.zone/app/account): 余额与流水、充值订单（iDataRiver 收款，多种支付方式）、登录设备、API Key、已授权应用

## API

- [API 索引](https://disk.zone/api): 全部公开接口的 JSON 描述：方法、路径、参数 JSON Schema、是否需要登录
- [OpenAPI 3.1](https://disk.zone/api/openapi.json): 同一套接口的 OpenAPI 文档，可导入 API 客户端或代码生成器
- [注册](https://disk.zone/api/auth/register): POST /api/auth/register（auth_register）— 用账号 + 密码注册，成功后自动登录。
- [登录](https://disk.zone/api/auth/login): POST /api/auth/login（auth_login）— 账号 + 密码登录，签发 15 分钟有效的 access_token（JWT, HS256）与 30 天滑动续期的 refresh_token。
- [续期](https://disk.zone/api/auth/refresh): POST /api/auth/refresh（auth_refresh）— 用 refresh_token 换一对新令牌（refresh_token 每次轮换；旧令牌 30 秒内重放视为并发请求，超出即判定被盗用并注销该会话）。
- [退出登录](https://disk.zone/api/auth/logout): POST /api/auth/logout（auth_logout，需登录）— 注销当前会话（all=true 时注销该账号的全部会话）。
- [检查账号是否可用](https://disk.zone/api/auth/username/{username}): GET /api/auth/username/{username}（auth_username_check）— 注册前检查账号格式与是否已被占用（查 KV 索引）。
- [我的账户](https://disk.zone/api/me): GET /api/me（me_get，需登录）— 当前账号资料、余额与各项目角色（余额以 micro 单位精确存储：1 = 1,000,000 micros；roles 形如 {"main":"admin","kv":"user"}，"*" 表示全部项目）。
- [余额流水](https://disk.zone/api/me/ledger): GET /api/me/ledger（me_ledger，需登录）— 余额变动明细（倒序，按 before 翻页）。
- [登录设备](https://disk.zone/api/me/sessions): GET /api/me/sessions（me_sessions，需登录）— 当前账号所有有效会话。
- [注销某个设备](https://disk.zone/api/me/sessions/{sid}): DELETE /api/me/sessions/{sid}（me_session_revoke，需登录）— 注销指定会话。
- [修改密码](https://disk.zone/api/me/password): POST /api/me/password（me_password，需登录）— 校验原密码后修改，并注销其他所有会话。
- [我的 API Key](https://disk.zone/api/me/keys): GET /api/me/keys（me_keys_list，需登录）— 当前账号的 API Key（不含密钥本身）。
- [创建 API Key](https://disk.zone/api/me/keys): POST /api/me/keys（me_key_create，需登录）— 创建一个 API Key。
- [吊销 API Key](https://disk.zone/api/me/keys/{id}): DELETE /api/me/keys/{id}（me_key_revoke，需登录）— 立即吊销指定的 API Key，使用它的请求随即失效。
- [充值选项](https://disk.zone/api/billing/options): GET /api/billing/options（billing_options）— 充值是否开放、套餐（sku 模式）或金额范围（custom 模式）、可用支付方式。
- [创建充值订单](https://disk.zone/api/billing/orders): POST /api/billing/orders（billing_order_create，需登录）— 在 iDataRiver 下单（sku 模式传 package_id，custom 模式传 amount），返回本站订单与可选支付方式；随后调用 billing_order_pay 获取支付链接。
- [获取支付链接](https://disk.zone/api/billing/orders/{id}/pay): POST /api/billing/orders/{id}/pay（billing_order_pay，需登录）— 为待支付订单选择支付方式并获取 iDataRiver 支付链接（pay_url）。
- [查询订单](https://disk.zone/api/billing/orders/{id}): GET /api/billing/orders/{id}（billing_order_get，需登录）— 查询订单；待支付订单会向 iDataRiver 同步一次真实状态（最多每 5 秒一次），已支付则自动入账。
- [我的订单](https://disk.zone/api/billing/orders): GET /api/billing/orders（billing_orders_list，需登录）— 当前账号的充值订单（倒序）。
- [产品列表](https://disk.zone/api/products): GET /api/products（products_list）— disk.zone 的三项存储产品及开放状态。
- [授权页信息](https://disk.zone/api/oauth/authorize/context): POST /api/oauth/authorize/context（oauth_authorize_context）— 授权页（/oauth/authorize）加载时调用：校验第三方应用的授权请求，返回应用信息、请求的权限（scopes）、当前登录用户与是否需要用户确认。
- [同意或拒绝授权](https://disk.zone/api/oauth/authorize/decision): POST /api/oauth/authorize/decision（oauth_authorize_decision，需登录）— 用户在授权页点「同意」（approve=true）或「拒绝」（approve=false）。
- [已授权应用](https://disk.zone/api/me/apps): GET /api/me/apps（me_apps，需登录）— 当前账号授权过的第三方应用（OAuth / OpenID Connect）：应用信息、授予的权限、首次授权与最近使用时间、仍有效的令牌数（active_tokens）。
- [撤销应用授权](https://disk.zone/api/me/apps/{client_id}): DELETE /api/me/apps/{client_id}（me_app_revoke，需登录）— 撤销对某个第三方应用的授权：删除授权记录，并立即吊销该应用持有的全部令牌（access_token、refresh_token 随即失效）。
- [同域登录状态](https://disk.zone/api/sso/me): GET /api/sso/me（sso_me）— 读取 disk.zone 的共享登录状态，返回 {user}（未登录为 null），user = {id, username, status}，id 即账号名。
- [同域退出登录](https://disk.zone/api/sso/logout): POST /api/sso/logout（sso_logout）— 注销 Cookie 所属的会话并清除全站（*.disk.zone）登录 Cookie，所有子项目随即看到已退出。

## 单点登录与 OAuth

- [开发者文档](https://disk.zone/developers): *.disk.zone 子项目的同域静默单点登录，以及第三方网站的 OAuth 2.0 接入说明
- [OpenID Connect 配置](https://disk.zone/.well-known/openid-configuration): 授权码 + PKCE，ES256 签名，sub 即用户 ID
- [SSO SDK](https://disk.zone/sdk/sso.js): window.DiskZone = { me(), login(), logout(), onChange(cb) }；第三方网站用 DiskZone.authorizeUrl(...) 发起 OAuth 跳转

## Optional

- [首页](https://disk.zone/): disk.zone 产品介绍
- [健康检查](https://disk.zone/api/health): 服务状态