如何把 Docker 应用上架到 1Panel 本地应用商店！

给 1Panel 应用商店新增一个应用，真正麻烦的从来不是写一份 docker-compose.yml——而是把一整套应用包格式整理完整：

• 应用信息要规范；
• data.yml 字段要齐；
• 表单参数要能在 1Panel 中正确配置；
• 端口、环境变量、数据卷不能写错；
• README 要能让用户看懂；
• 目录权限、初始化脚本不能凭感觉补；
• 最后还要能放到本地应用目录里跑起来。

这些事情不难，但很琐碎，也很容易因为复制模板、漏字段、猜参数而返工。

为此，1Panel 官方整理了一个专门面向应用封装的 Skill：1panel-appstore-skills。仓库地址：github.com/1Panel-dev/1Panel-appstore-skills。

一、它解决的核心问题

1panel-appstore-skills 面向已经支持 Docker 化部署的应用，根据官方仓库、官方文档、Docker 镜像、docker-compose.yml，或已整理好的中间 spec，生成符合 1Panel 应用商店应用格式的安装包。它重点解决三件事：

1. 少手写重复模板

自动生成 1Panel 应用包所需的目录结构、data.yml、docker-compose.yml、README 与数据目录，不必逐个文件复制粘贴。

2. 少踩格式坑

应用商店包不只是 Compose 文件，还涉及版本目录、表单字段、多语言描述、容器名称、端口变量、持久化路径等规则。Skill 会按官方应用包结构统一生成。

3. 少凭经验猜部署参数

镜像、端口、环境变量、数据卷、运行用户与目录权限等信息，优先来自应用官方仓库或官方文档——避免"能写出来但跑不稳"。

二、信息来源原则

这是这个 Skill 最核心的设计取向：应用包中的 Docker 安装方式必须来自应用官方仓库或官方文档。具体规则：

• 提供仓库地址时，优先以该仓库为主线来源；
• 没有仓库地址时，才去 GitHub、Gitee、GitLab 等主流开源代码仓库查找，并确认是官方仓库；
• 可参考的素材：仓库内的 README、docs、docker-compose.yml、compose.yml、Dockerfile、.env.example、部署文档，以及官方文档站点中明确给出的 Docker / Docker Compose 安装说明；
• 容器运行用户、UID/GID、数据目录权限等信息，需要来自官方 Dockerfile、Compose 文件或镜像文档；
• 没有 Docker 安装方式时，需先补充可靠的容器化信息再生成应用包；
• 优先使用官方容器镜像；只在用户明确接受时才使用第三方镜像，并记录来源。

三、适合什么场景

适合：

• 把一个 Docker 化应用封装成 1Panel 应用商店应用；
• 把官方仓库或官方文档中的 Docker / Docker Compose 安装方式转换为 1Panel 应用包；
• 把现有 docker-compose.yml 整理为 1Panel 应用商店目录结构；
• 基于已准备好的 app spec 生成完整应用包。

不适合：

• 应用没有可靠的 Docker 化安装方式；
• 需要凭空设计部署架构、镜像、端口、数据目录或环境变量；
• 需要直接发布到远程应用商店仓库（本 Skill 只负责生成应用包内容）。

四、项目结构

1panel-appstore-skills/
├── README.md
├── README.zh-CN.md
├── SKILL.md
├── assets/
├── references/
└── scripts/

核心文件：

• SKILL.md：定义 Skill 的触发场景、工作流程与封装规则；
• assets/sample-appspec.json：中间 spec 示例；
• references/appstore-format.md：1Panel 应用包目录与字段规则；
• references/source-policy.md：应用源码、官方文档与 Docker 安装方式的来源规则；
• scripts/generate_app_package.py：根据中间 spec 生成 1Panel 应用包。

五、生成的应用包结构

apps/<app-key>/
├── logo.png
├── README.md
├── README_en.md
├── data.yml
└── <version>/
    ├── data.yml
    ├── docker-compose.yml
    ├── data/
    └── scripts/        # 可选：需要处理持久化目录权限时生成 init.sh

说明：

• 应用基础信息、版本、类型、标签、网站、文档与仓库地址会自动整理；
• 主服务与依赖服务的镜像、端口、环境变量、数据卷、启动依赖会按官方来源生成；
• 中文 README 默认生成；当官方资料支持英文时同步生成英文 README；
• scripts/init.sh 仅在官方来源能证明需要时生成（当前最常见的用途是处理持久化目录权限）。没有初始化动作时，应用包不包含 scripts/ 目录。

六、使用示例

直接告诉 Skill 你要做什么即可：

帮我把 https://github.com/example/myapp 封装成 1Panel 应用商店应用。

帮我把 OpenClaw 封装成 1Panel 应用商店应用。

帮我把 ghcr.io/example/myapp:1.0.0 封装成 1Panel 应用商店应用。
对外端口 8080，容器端口 3000。

使用 1panel-appstore-skills，把当前目录的 docker-compose.yml
转成 1Panel 应用商店应用包。

七、命令行生成

如果已经准备好符合 references/appspec.md 的中间 spec，可以直接运行脚本生成：

python3 scripts/generate_app_package.py \
  --spec assets/sample-appspec.json \
  --output apps

生成后会得到一个完整的应用包目录 apps/<app-key>。

八、它不会做什么

这个 Skill 的定位很明确：把可靠的 Docker 化部署资料整理成 1Panel 应用包。它不会替你凭空设计部署方案：

• 不凭空猜镜像；
• 不凭空猜端口；
• 不凭空猜环境变量；
• 不凭空猜数据目录；
• 不直接发布到远程应用商店仓库。

九、本地验证

把生成的应用目录放到 1Panel 本地应用目录：

/opt/1panel/resource/apps/local/<app-key>

然后在 1Panel 应用商店中点击刷新本地应用列表，依次测试：

• 安装
• 启动 / 停止 / 重启
• 卸载

这一步强烈建议执行——应用包结构生成出来只是第一步，真正可用还要看端口、权限、变量、持久化目录在实际环境中是否都能正常工作。

十、写在最后

1panel-appstore-skills 最适合接手那些"重复但不能随便写"的工作。它让 1Panel 应用封装从手工拼文件，变成基于官方来源、按应用商店规范生成应用包。

对于经常需要把 Docker 化应用整理成 1Panel 应用的开发者与上架者，可以显著降低模板整理与格式校对成本，把更多精力留给真正重要的两件事——来源确认与安装验证。

参考链接

• 1panel-appstore-skills 仓库：https://github.com/1Panel-dev/1Panel-appstore-skills
• 1Panel 主仓库：https://github.com/1Panel-dev/1Panel
• 1Panel 官方文档：https://1panel.cn/docs/