开发文档

把 APK 分发接进你的工作流

三分钟完成第一次发布,或用 REST API / CLI 接入现有 CI/CD。

快速开始

本平台是一个零依赖 Node.js 应用,默认监听 8787 端口,数据保存在 data/,安装包保存在 uploads/。

bash
# 1. 启动服务
node src/server.js
# 或双击 start.bat(Windows)

# 2. 打开管理后台
# http://localhost:8787/admin

# 3. 登录后新建应用并上传 APK

首次启动会生成默认管理员账号 admin / admin123456,请登录后立即在「设置」中修改密码,或通过环境变量 ADMIN_PASSWORD 指定。

上传应用

有三种方式发布版本,上传后会自动解析包名、版本号、最低系统版本并提取启动图标。

1. 管理后台上传

进入「应用」→ 选择或新建应用 → 拖拽 APK → 填写更新日志 → 发布。

2. REST API 上传

bash
curl -X POST "https://noshul.chen1413.com.cn:443/api/v1/apps/my-app/versions" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@app-release.apk" \
  -F "changelog=修复登录问题,优化启动速度"

3. 命令行上传

bash
node tools/cli.js upload \
  --server https://noshul.chen1413.com.cn:443 \
  --token $TOKEN \
  --app my-app \
  --file app-release.apk \
  --changelog "CI 自动构建"

开放 API

在后台「API 令牌」页面创建 Token。除公开下载页外,所有接口都需要在请求头携带:

bash
Authorization: Bearer fd_xxxxxxxxxxxxxxxx
方法路径说明
GET/api/v1/apps获取应用与版本列表
POST/api/v1/apps创建应用
GET/api/v1/apps/:slug获取单个应用详情
POST/api/v1/apps/:slug/versions上传新版本(multipart)
DELETE/api/v1/apps/:slug删除应用及所有文件

创建应用

需先在「站点设置」中开启「允许开放 API 创建应用」。

bash
curl -X POST "https://noshul.chen1413.com.cn:443/api/v1/apps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"我的应用","description":"内测版本","protected":false}'

上传版本

bash
curl -X POST "https://noshul.chen1413.com.cn:443/api/v1/apps/my-app/versions" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@app-release.apk" \
  -F "versionName=1.2.0" \
  -F "changelog=新增消息中心"

查询列表

bash
curl "https://noshul.chen1413.com.cn:443/api/v1/apps" -H "Authorization: Bearer $TOKEN"

访问控制

开启访问保护后,下载页与安装包都需要先输入密码。可在后台应用详情中设置,也可通过 API 传入:

bash
curl -X POST "https://noshul.chen1413.com.cn:443/api/v1/apps" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"内部灰度","protected":true,"password":"beta2026"}'

访问验证成功后,浏览器会保存一个 30 天有效的签名 Cookie,无需重复输入密码。

二维码与短链

每个应用自动拥有以下地址:

类型地址
下载页https://noshul.chen1413.com.cn:443/a/<slug>
短链(跳转下载页)https://noshul.chen1413.com.cn:443/s/<slug>
最新版直链https://noshul.chen1413.com.cn:443/d/<slug>
二维码https://noshul.chen1413.com.cn:443/a/<slug>/qr.svg
图标https://noshul.chen1413.com.cn:443/a/<slug>/icon

二维码以 SVG 返回,可直接嵌到网页或海报中:

html
<img src="https://noshul.chen1413.com.cn:443/a/my-app/qr.svg" width="180" alt="下载二维码">

自定义短链域名

在后台「站点设置 → 短链域名」填写独立域名(例如 s.example.com),并把该域名解析到本服务。 之后在「短链接」页面创建跳转:目标可以是站内路径(/ 开头)或完整 http(s) 链接, 短码可自定义或自动生成,最终得到形如 https://s.example.com/abc123 的短链。

text
# 目标为应用下载页
https://s.example.com/myapp  ->  /a/my-app

# 目标为最新版直链
https://s.example.com/latest  ->  /d/my-app

访问短链会返回 302 跳转,并在「短链接」列表中累计点击次数。未配置独立域名时, 短链使用主站的 /s/<code> 路径;根路径 /<code> 同样可用。 Nginx 中将该域名与主站指向同一上游即可。

Webhook

在后台「站点设置」中配置回调地址。每次发布新版本会收到一个 JSON POST:

json
{
  "event": "version.published",
  "app": { "id": "...", "name": "我的应用", "slug": "my-app", "package": "com.example.app" },
  "version": { "id": "...", "versionName": "1.2.0", "versionCode": 120, "size": 25800000, "sha256": "...", "changelog": "..." },
  "urls": {
    "page": "https://noshul.chen1413.com.cn:443/a/my-app",
    "download": "https://noshul.chen1413.com.cn:443/a/my-app/download/...",
    "qr": "https://noshul.chen1413.com.cn:443/a/my-app/qr.svg"
  }
}

请求头 X-CloudArk-Secret 为后台生成的校验密钥,请在你的服务端校验来源。

命令行工具

tools/cli.js 仅使用 Node.js 内置能力,无第三方依赖,可在 CI 中直接运行。

bash
# 查看帮助
node tools/cli.js --help

# 列出应用
node tools/cli.js list --server https://noshul.chen1413.com.cn:443 --token $TOKEN

# 上传版本
node tools/cli.js upload --server https://noshul.chen1413.com.cn:443 --token $TOKEN \
  --app my-app --file app-release.apk --changelog "自动构建 #42"

数据与备份

所有元数据保存在 data/db.json(自动维护 db.json.bak),图标在 data/icons/,安装包在 uploads/<appId>/。

备份时只需复制 data/ 与 uploads/ 两个目录;迁移到新服务器后保持目录结构即可。

bash
# Linux / macOS 定时备份示例
tar czf cloudark-backup-$(date +%F).tar.gz data uploads

环境变量

变量默认值说明
PORT8787监听端口
HOST0.0.0.0监听地址
ADMIN_USERadmin管理员用户名(仅首次初始化)
ADMIN_PASSWORDadmin123456初始管理员密码(仅首次初始化)
MAX_UPLOAD_MB500APK 上传大小上限
PUBLIC_URL自动识别生成二维码/链接使用的公网地址
DATA_DIR./data数据目录
UPLOADS_DIR./uploads安装包目录