my-app/
  manifest.json      ← 唯一手写的文件
  assets/icon.png    ← 图标（PNG / JPEG / WebP / SVG）
  bin/app            ← 你的程序
  config/            ← 其他资源，可有可无

./app --listen=0.0.0.0:8080 --data=/var/lib/app

{
  "schema": 1,
  "id": "mdesk.example.myapp",
  "version": "1.0.0",
  "name": "示例应用",
  "description": "我的第一个 MPK 应用。",
  "architectures": ["amd64"],
  "icon": "assets/icon.png",
  "runtime": "native",
  "web": { "listen": "port", "openPath": "/", "healthPath": "/healthz" },
  "native": {
    "executable": "bin/app",
    "args": ["--listen=0.0.0.0:${MDESK_PORT}", "--data=${MDESK_DATA_DIR}"],
    "workingDir": "."
  }
}

mpkpack validate ../my-app
mpkpack build ../my-app --output ../dist/mdesk.example.myapp-1.0.0.mpk
mpkpack validate ../dist/mdesk.example.myapp-1.0.0.mpk

{
  "schema": 1,
  "id": "mdesk.example.myapp",
  "version": "1.0.0",
  "name": "示例应用",
  "description": "一句话说明这个应用。",
  "architectures": ["amd64", "arm64"],
  "icon": "assets/icon.png",
  "runtime": "native",
  "web": { "listen": "port", "openPath": "/", "healthPath": "/healthz" },
  "native": {
    "executable": "bin/app",
    "args": ["--listen=0.0.0.0:${MDESK_PORT}"],
    "workingDir": "."
  }
}

"architectures": ["amd64", "arm64"],
"native": { "executable": "bin/run", "args": ["--listen=0.0.0.0:${MDESK_PORT}"] }

#!/bin/sh
# bin/run —— 构建时只有它被设为 0755，其余文件是 0644
case "$(uname -m)" in
  x86_64|amd64)  BIN=app-amd64 ;;
  aarch64|arm64) BIN=app-arm64 ;;
  *) echo "unsupported arch: $(uname -m)" >&2; exit 1 ;;
esac
DIR="$(dirname "$0")"
chmod +x "$DIR/$BIN" 2>/dev/null || true   # 否则 permission denied
exec "$DIR/$BIN" "$@"

"runtime": "native",
"web": { "listen": "port", "preferredPort": 18080, "openPath": "/", "healthPath": "/healthz" },
"native": {
  "executable": "bin/app",
  "args": ["--listen=0.0.0.0:${MDESK_PORT}", "--data=${MDESK_DATA_DIR}"],
  "workingDir": "."
}

"runtime": "native",
"web": { "listen": "socket", "openPath": "/", "healthPath": "/healthz" },
"native": {
  "executable": "bin/app",
  "args": [
    "--socket=${MDESK_SOCKET}",
    "--base-path=${MDESK_BASE_PATH}",
    "--data=${MDESK_DATA_DIR}"
  ],
  "workingDir": "."
}

"runtime": "docker",
"web": { "listen": "port", "preferredPort": 18081, "openPath": "/", "healthPath": "/" },
"docker": { "compose": "docker-compose.yml" }

services:
  web:
    image: example/webapp:1.0.0
    ports:
      - "${MDESK_PORT}:8080"      # 宿主端口用变量，容器端口写死
    volumes:
      - "${MDESK_DATA_DIR}:/data"  # 不挂这里，升级后数据会丢
    restart: unless-stopped

"runtime": "docker",
"web": { "listen": "socket", "openPath": "/", "healthPath": "/healthz" },
"docker": { "compose": "docker-compose.yml" }

services:
  web:
    image: example/webapp:1.0.0
    command: ["--socket=/run/mdesk/app.sock", "--base-path=${MDESK_BASE_PATH}"]
    volumes:
      - "${MDESK_RUN_DIR}:/run/mdesk"   # Socket 目录挂进容器
      - "${MDESK_DATA_DIR}:/data"

const base = new URL(".", window.location.href);
function appUrl(path) {
  return new URL(path.replace(/^\/+/, ""), base).toString();
}

"args": ["--listen=0.0.0.0:${MDESK_PORT}", "--data=${MDESK_DATA_DIR}"]

#!/bin/sh
exec "$(dirname "$0")/bin/app" --listen="0.0.0.0:${MDESK_PORT}" --data="${MDESK_DATA_DIR}"

sha256sum -c checksums.txt

chmod +x mpkpack-linux-amd64
./mpkpack-linux-amd64 validate ../my-app

# 想直接用 mpkpack 这个名字，放进 PATH
sudo mv mpkpack-linux-amd64 /usr/local/bin/mpkpack

mpkpack init ../my-app \
  --id mdesk.example.myapp \
  --name "示例应用" \
  --runtime native \
  --listen socket

# 1. 校验源目录
mpkpack validate ../my-app

# 2. 构建
mpkpack build ../my-app --output ../dist/mdesk.example.myapp-1.0.0.mpk

# 3. 校验成品
mpkpack validate ../dist/mdesk.example.myapp-1.0.0.mpk

"store": {
  "category": "工具",
  "author": "M·Desk",
  "developer": "示例团队"
}

mpkpack build ../my-app --output ../dist/mdesk.example.myapp-1.0.0.mpk

# 1. 打包
mpkpack build ./my-app -output ./dist/example.app-1.0.0.mpk

# 2. 生成源目录
mpkpack store ./dist/example.app-1.0.0.mpk --store-dir ./my-store

# 3. 把这个目录整个传到网上，比如放到 https://apps.example.com/mystore/

manifest.json 里你写的        id = "example.app"
mpkpack store 入库后         id = "mdesk.example.app"     ← index.json 里长这样
用户在应用中心看到的          id = "myco.example.app"      ← 前缀由系统分配

mdesk   casaos   1panel   official   installed   thirdparty   online

# 先改 manifest 里的 version，重新打包
mpkpack build ./my-app -output ./dist/example.app-1.1.0.mpk
# 再入库，覆盖旧条目
mpkpack store ./dist/example.app-1.1.0.mpk --store-dir ./my-store --force

<数据目录>/mdeskapps/
  catalog-cache.json                 ← M·Desk 官方源
  sources/
    myco/catalog-cache.json          ← 你的源
    other/catalog-cache.json         ← 别人的源

my-store/
  index.json                          ← 清单：有哪些应用
  thirdparty.demo.json                ← 详情，文件名 = packageId + .json
  icons/
    thirdparty.demo.svg               ← 图标，独立文件
  packages/
    thirdparty.demo-1.0.0.mpk         ← 安装包本体

{
  "schema": 1,
  "name": "M·Desk 应用",
  "updatedAt": "2026-10-22T19:01:54+08:00",
  "apps": [
    {
      "schema": 1,
      "id": "mdesk.thirdparty.demo",
      "packageId": "thirdparty.demo",
      "name": "三方示例",
      "summary": "来自三方订阅源的示例应用",
      "category": "工具",
      "version": "1.0.0",
      "author": "Third Party",
      "developer": "第三方开发者",
      "icon": "icons/thirdparty.demo.svg",
      "detail": "thirdparty.demo.json",
      "introduction": "来自三方订阅源的示例应用"
    }
  ]
}

{
  "schema": 1,
  "id": "mdesk.thirdparty.demo",
  "packageId": "thirdparty.demo",
  "name": "三方示例",
  "summary": "来自三方订阅源的示例应用",
  "category": "工具",
  "version": "1.0.0",
  "author": "Third Party",
  "developer": "第三方开发者",
  "icon": "icons/thirdparty.demo.svg",
  "detail": "thirdparty.demo.json",
  "introduction": "来自三方订阅源的示例应用",
  "package": {
    "path": "packages/thirdparty.demo-1.0.0.mpk",
    "sha256": "51b39a0b8e4ffc57443ffa80eb778a1d147f91c9a2759b5532bfb67028f2f478",
    "size": 763
  }
}

GET  <地址>index.json              读清单
GET  <地址><detail>               读某个应用的详情
GET  <地址><icon>                 取图标
GET  <地址><package.path>         下载安装包
     ↓
     逐字节校验 sha256 与 size，通过才装

my-app/
  wizard/
    install.json   ← 安装时展示（可选）
    config.json    ← 已安装后在「应用设置」里展示（可选）

"wizard": {
  "install": "wizard/install.json",
  "config":  "wizard/config.json",
  "bindings": {
    "preferredPort": "${field.port}",
    "native": { "env": { "APP_HOME": "${field.home}" } }
  }
}

{
  "steps": [
    {
      "stepTitle": "基本设置",
      "items": [
        { "field": "port", "type": "number", "label": "端口",
          "initValue": 7863, "min": 1024, "max": 65535 },
        { "field": "home", "type": "text", "label": "主页",
          "initValue": "https://example.com/", "required": true }
      ]
    }
  ]
}

environment:
  APP_HOST: "${APP_HOST}"        # 对
  # APP_HOST: "${field.host}"    # 错，Compose 报 invalid interpolation format