ImgYoung
DocsAPI
API reference

Admin · Storage channels

Channel templates, creation, editing, probing, deletion and cloud drive authorization

渠道模板清单

GET
/api/admin/channel-templates

内置厂商模板：预填 rclone 后端与固定参数，只暴露必要字段；只下发结构（模板 id、字段 key 与类型、选项值），模板名、字段标签、说明与选项显示名由前端词典按这些键提供。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Response Body

模板清单

application/json
  1. response
items*array<>
total*integer
Formatint64
curl -X GET 'http://localhost:8721/api/admin/channel-templates'
{  "items": [    {      "id": "aws-s3",      "driver": "string",      "category": "object_storage",      "requires_oauth": true,      "fields": [        {          "key": "access_key_id",          "type": "text",          "required": true,          "options": [            "us-east-1"          ]        }      ]    }  ],  "total": 0}

渠道列表

GET
/api/admin/channels

按优先级降序，含探测结果与副本水位，不含配置与凭证。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Response Body

渠道列表

application/json
  1. response
items*array<>
total*integer
Formatint64
curl -X GET 'http://localhost:8721/api/admin/channels'
{  "items": [    {      "id": 0,      "name": "string",      "driver": "string",      "priority": 0,      "healthy": true,      "encrypted": true,      "allow_direct_link": true,      "last_checked_at": "string",      "last_error": "string",      "deleting": true,      "replicas": {        "done": 0,        "pending": 0,        "failed": 0      },      "created_at": "string"    }  ],  "total": 0}

创建渠道

POST
/api/admin/channels

模板模式给 template + inputs，自定义模式给 driver + config。需授权的模板会先按后端配置流程补齐授权带出的参数（如 OneDrive 选定用户默认驱动器），向服务商查询失败返回 400。创建即深探测并落库，随后唤醒补齐管道回填存量；encrypted 创建时固化。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body

配置来源二选一：模板模式给 template + inputs；自定义模式 template 为空或 custom，给 driver + config。未知字段整体拒绝

template?string

模板 id；空或 custom 走自定义

inputs?

模板字段值

driver?string

自定义模式的 rclone 后端名

config?

自定义模式的后端参数，含约定键 path（后端内路径）与 public_base_url（302 直链前缀）

name*string

渠道名，唯一

priority?integer

越大越优先；缺省 0

Formatint64
encrypted?boolean

是否加密渠道；缺省用全局默认，创建时固化

allow_direct_link?boolean

是否允许 302 直链；缺省 false

auto_create_bucket?boolean

创建时主动建桶，需凭证有建桶权限；缺省 false

Response Body

渠道的完整描述（含探测结果与副本水位）

application/json
  1. response

渠道的对外描述，不含配置与凭证

id*integer
Formatint64
name*string
driver*string

rclone 后端名

priority*integer

越大越优先

Formatint64
healthy*boolean
encrypted*boolean
allow_direct_link*boolean
last_checked_at*string

最近探测时刻；空表示尚未探测

last_error*string

最近探测失败原因，渠道装载失败时以「装载失败」开头；空表示最近一次探测成功

deleting*boolean

清理中：排空任务正在删除渠道上的对象，清完即消失

replicas*

渠道的副本补齐水位

created_at*string

创建时刻；与 id 一起参与加密渠道 crypt 密码与盐的派生

curl -X POST 'http://localhost:8721/api/admin/channels' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
{  "id": 0,  "name": "string",  "driver": "string",  "priority": 0,  "healthy": true,  "encrypted": true,  "allow_direct_link": true,  "last_checked_at": "string",  "last_error": "string",  "deleting": true,  "replicas": {    "done": 0,    "pending": 0,    "failed": 0  },  "created_at": "string"}

测试连接

POST
/api/admin/channels/test

按创建同构的请求体深探测，不落库；探测成败以 {ok, error} 返回，补齐授权带出的参数时向服务商查询失败也在其中。授权令牌已过期时测试期间会被刷新：提交的是新令牌（创建表单，或编辑时新粘贴 / 新授权的令牌）时，刷新后的令牌随 token 返回；沿用已存令牌（哨兵）时直接写回该渠道，不返回。编辑场景带 channel_id，配置里的哨兵值还原为该渠道原凭证后再探测。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body

配置来源二选一：模板模式给 template + inputs；自定义模式 template 为空或 custom，给 driver + config。未知字段整体拒绝

template?string

模板 id；空或 custom 走自定义

inputs?

模板字段值

driver?string

自定义模式的 rclone 后端名

config?

自定义模式的后端参数，含约定键 path（后端内路径）与 public_base_url（302 直链前缀）

name*string

渠道名，唯一

priority?integer

越大越优先；缺省 0

Formatint64
encrypted?boolean

是否加密渠道；缺省用全局默认，创建时固化

allow_direct_link?boolean

是否允许 302 直链；缺省 false

auto_create_bucket?boolean

创建时主动建桶，需凭证有建桶权限；缺省 false

channel_id?integer

编辑场景传渠道 id，配置中的哨兵值还原为原凭证后再探测；0 或缺省为创建场景

Formatint64

Response Body

探测结果

application/json
  1. response
ok*boolean

探测是否通过

error?string

失败原因，不含凭证

token?string

测试期间服务商刷新了提交的授权令牌时出现，值为刷新后的令牌 JSON（与 rclone 的 token 参数同格式）； 探测失败时也可能出现。存在时前端须用它替换表单里的令牌再保存——刷新令牌只能用一次的服务商（如 Box）， 原令牌已被作废。模板模式替换授权字段（inputs.token），自定义模式替换 config.token。只回传令牌，不回传其他凭证

curl -X POST 'http://localhost:8721/api/admin/channels/test' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
{  "ok": true,  "error": "string",  "token": "string"}

删除渠道

DELETE
/api/admin/channels/{id}

持有任何图唯一副本的渠道拒绝删除（409）。purge 缺省为 true：只打清理中标记并入队排空任务，排空任务删除本服务写在该渠道上的对象——图片副本、_imgyoung/ 下的系统对象（含元数据库快照）与深探测残留，别的程序写的对象不动——删完后渠道才消失（202）；purge=false 立即删行，远端对象（含快照）保留（204）。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*integer

渠道 id

Formatint64

Query Parameters

purge?boolean

是否清理本服务写在渠道上的对象；缺省 true

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Response Body

已标记清理中，对象删完后移除

curl -X DELETE 'http://localhost:8721/api/admin/channels/0' \  -H 'X-CSRF-Token: string'
Empty

编辑渠道

PUT
/api/admin/channels/{id}

配置整体替换；配置里原样回传的哨兵值表示保留原凭证，只在回读时掩码过的敏感参数上有效，落在其他键上返回 400。encrypted 不可变，试图变更返回 409。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*integer

渠道 id

Formatint64

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body

与创建同构，PUT 为全量语义，须给出全部键；配置里原样回传的哨兵值表示保留原凭证

template?string
inputs?
driver?string
config?
name*string
priority*integer
Formatint64
encrypted?boolean

可回传但必须与现状一致

allow_direct_link*boolean

Response Body

渠道的完整描述（含探测结果与副本水位）

application/json
  1. response

渠道的对外描述，不含配置与凭证

id*integer
Formatint64
name*string
driver*string

rclone 后端名

priority*integer

越大越优先

Formatint64
healthy*boolean
encrypted*boolean
allow_direct_link*boolean
last_checked_at*string

最近探测时刻；空表示尚未探测

last_error*string

最近探测失败原因，渠道装载失败时以「装载失败」开头；空表示最近一次探测成功

deleting*boolean

清理中：排空任务正在删除渠道上的对象，清完即消失

replicas*

渠道的副本补齐水位

created_at*string

创建时刻；与 id 一起参与加密渠道 crypt 密码与盐的派生

curl -X PUT 'http://localhost:8721/api/admin/channels/0' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string",  "priority": 0,  "allow_direct_link": true}'
{  "id": 0,  "name": "string",  "driver": "string",  "priority": 0,  "healthy": true,  "encrypted": true,  "allow_direct_link": true,  "last_checked_at": "string",  "last_error": "string",  "deleting": true,  "replicas": {    "done": 0,    "pending": 0,    "failed": 0  },  "created_at": "string"}

渠道配置的编辑视图

GET
/api/admin/channels/{id}/config

后端声明为密码或敏感信息的参数（rclone 选项元数据的 IsPassword / Sensitive，含访问密钥 ID、账号名、OAuth 应用凭证与令牌）以哨兵 __imgyoung_secret_keep__ 掩码，明文永不下发；模板渠道附带还原出的表单字段值，同一口径掩码。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*integer

渠道 id

Formatint64

Response Body

编辑视图

application/json
  1. response

渠道配置的编辑视图，敏感值以哨兵掩码

template*string

配置所用模板 id；空表示自定义

driver*string
config*

掩码后的后端参数

inputs?

模板表单字段值，落在敏感参数上的字段同样以哨兵掩码；仅模板渠道

curl -X GET 'http://localhost:8721/api/admin/channels/0/config'
{  "template": "string",  "driver": "string",  "config": {    "property1": "string",    "property2": "string"  },  "inputs": {    "property1": "string",    "property2": "string"  }}

导出 rclone 配置

GET
/api/admin/channels/{id}/rclone-config

以附件输出一份标准 rclone 可直接使用的配置文件（rclone.conf），凭它可脱离 ImgYoung 读写渠道数据。 远端 imgyoung-<渠道 id> 的参数与渠道后端所用完全一致，含凭证与授权令牌，密码类参数按 rclone 规则以 obscure 形式写出； 加密渠道另有远端 imgyoung-<渠道 id>-crypt，指向渠道存储路径，参数与服务端的 crypt 层一致（password / password2 为 obscure 形式，filename_encryption = standard）。文件头的 # 注释说明各远端与用法。 文件里的凭证与解密密码与主密钥同等敏感；响应不缓存，每次下载记一条 channel.export 审计日志。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*integer

渠道 id

Formatint64

Response Body

rclone 配置文件

response?stringtext/plain
curl -X GET 'http://localhost:8721/api/admin/channels/0/rclone-config'
"string"

手动重检

POST
/api/admin/channels/{id}/check

对已有渠道执行深探测并返回探测后的完整描述；此前装载失败的渠道先重试装载，仍装不上则以装载失败作为结论。探测可能持续数十秒。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Path Parameters

id*integer

渠道 id

Formatint64

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Response Body

渠道的完整描述（含探测结果与副本水位）

application/json
  1. response

渠道的对外描述，不含配置与凭证

id*integer
Formatint64
name*string
driver*string

rclone 后端名

priority*integer

越大越优先

Formatint64
healthy*boolean
encrypted*boolean
allow_direct_link*boolean
last_checked_at*string

最近探测时刻；空表示尚未探测

last_error*string

最近探测失败原因，渠道装载失败时以「装载失败」开头；空表示最近一次探测成功

deleting*boolean

清理中：排空任务正在删除渠道上的对象，清完即消失

replicas*

渠道的副本补齐水位

created_at*string

创建时刻；与 id 一起参与加密渠道 crypt 密码与盐的派生

curl -X POST 'http://localhost:8721/api/admin/channels/0/check' \  -H 'X-CSRF-Token: string'
{  "id": 0,  "name": "string",  "driver": "string",  "priority": 0,  "healthy": true,  "encrypted": true,  "allow_direct_link": true,  "last_checked_at": "string",  "last_error": "string",  "deleting": true,  "replicas": {    "done": 0,    "pending": 0,    "failed": 0  },  "created_at": "string"}

发起网盘授权

POST
/api/admin/channel-oauth/start

返回引导用户前往的授权地址与领取结果用的一次性 state。需先配置对外站点地址 base_url，回调地址由它拼出并须与开放平台登记值逐字符一致；自建应用的 Client ID / Secret 是模板字段，随 inputs 提交并随渠道保存。编辑场景带 channel_id，字段里的哨兵还原为该渠道已存值后再发起。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Header Parameters

X-CSRF-Token*string

登录或 GET /api/admin/me 响应里的 csrf_token；缺失或不匹配返回 403

Request Body

application/json
  1. body
template*string

模板 id，须为需要授权的模板

inputs?

已填字段值：区域等影响端点的参数与自建应用的 client_id / client_secret；授权令牌字段不参与

channel_id?integer

编辑场景传渠道 id，字段中的哨兵还原为该渠道已存值；0 或缺省为创建场景

Formatint64

Response Body

授权地址

application/json
  1. response
auth_url*string

引导用户前往的授权地址

Formaturi
state*string

领取结果用的一次性标识

curl -X POST 'http://localhost:8721/api/admin/channel-oauth/start' \  -H 'X-CSRF-Token: string' \  -H 'Content-Type: application/json' \  -d '{  "template": "string"}'
{  "auth_url": "http://example.com",  "state": "string"}

授权回调

GET
/api/admin/channel-oauth/callback

由授权服务器把浏览器顶层跳转打回，换取令牌后交前端凭 state 领取；本端点返回提示页而非 JSON，令牌不写进页面。仅管理员会话。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Query Parameters

state*string

发起授权时得到的一次性标识

code?string

授权码；用户拒绝时缺省

error?string

授权服务器报告的拒绝原因

Response Body

提示页；授权成功与失败都在此页提示，结果由领取接口给出

response?stringtext/html
curl -X GET 'http://localhost:8721/api/admin/channel-oauth/callback?state=string'
"string"

领取授权结果

GET
/api/admin/channel-oauth/result

结果只可领取一次；用户尚未完成授权时 pending 为 true。仅管理员。

Authorization

session
cookieimgyoung_session<token>

登录下发的会话 cookie；状态变更请求须另以 X-CSRF-Token 头回传会话绑定的 CSRF 令牌。

Query Parameters

state*string

发起授权时得到的一次性标识

Response Body

授权结果

application/json
  1. response
pending*boolean

用户尚未完成授权

token?string

授权令牌，填入渠道表单后随渠道提交

error?string

授权失败原因

curl -X GET 'http://localhost:8721/api/admin/channel-oauth/result?state=string'
{  "pending": true,  "token": "string",  "error": "string"}

Admin · Upload tokens

Issuing, rotating and revoking named upload tokens, and their S3 credentials

Admin · Users

User accounts, quotas and password resets (admins only)