--- title: 为1Panel添加自己想要的应用 categories: 技术 tags: 1panel cover: https://pic.biss.click/image/fa0178dd-b1f6-48eb-8690-42faf26c9f52.webp abbrlink: bb18d851 summary: 为1Panel添加自己想要的应用 date: 2025-08-19 10:43:16 --- 记录一下自己为1Panel贡献自己应用的经历 # 预准备 1. Fork仓库 {% link 1Panel appstore 仓库,1panel appstore,https://github.com/1Panel-dev/appstore %} 把仓库fork到自己的仓库 2. pull ```bash git clone -b dev https:///appstore ``` 创建新分支 ```bash cd appstore git checkout -b app/ ``` # 创建文件 ## 文件目录 ``` ├──halo // 以 halo 的 key 命名 ，下面解释什么是 key ├── logo.png // 应用 logo , 最好是 180 * 180 px 不要超过 10 KB ├── data.yml // 应用声明文件 ├── README.md // 应用的 README ├── 2.2.0 // 应用版本 注意不要以 v 开头 │   ├── data.yml // 应用的参数配置，下面有详细介绍 │   ├── data // 挂载出来的目录 | ├── scripts // 脚本目录 存放 init.sh upgrade.sh uninstall.sh │   └── docker-compose.yml // docker-compose 文件 └── 2.3.2 ├── data.yml ├── data └── docker-compose.yml ``` ## 应用声明文件`data.yml` 本文件主要用于声明应用的一些信息 ```yml additionalProperties: #固定参数 key: halo #应用的 key ，仅限英文，用于在 Linux 创建文件夹 name: Halo #应用名称 tags: - WebSite #应用标签，可以有多个，请参照下方的标签列表 description: en: Powerful and easy-to-use open source website builder zh: 强大易用的开源建站工具 #应用中文描述，不要超过30个字 zh-Hant: ja: ms: pt-br: ru: ko: type: website #应用类型，区别于应用分类，只能有一个，请参照下方的类型列表 crossVersionUpdate: true #是否可以跨大版本升级 limit: 0 #应用安装数量限制，0 代表无限制 website: https://halo.run/ #官网地址 github: https://github.com/halo-dev/halo #github 地址 document: https://docs.halo.run/ #文档地址 ``` ## 应用标签 - tags 字段 | key | name | |----------|----------| | WebSite | 建站 | | Server | Web 服务器 | | Runtime | 运行环境 | | Database | 数据库 | | Tool | 工具 | | CI/CD | CI/CD | | Local | 本地 | # 应用类型 - type 字段 | type | 说明 | |---------|---------------------------------------------------------| | website | website 类型在 1Panel 中支持在网站中一键部署,wordpress halo 都是此 type | | runtime | mysql openresty redis 等类型的应用 | | tool | phpMyAdmin redis-commander jenkins 等类型的应用 | # 应用参数配置文件 data.yml （注意区分于应用主目录下面的 `data.yaml`） 本文件主要用于生成安装时要填写的 form 表单，在应用版本文件夹下面 可以无表单，但是需要有这个 data.yml文件，并且包含 formFields 字段 以安装 halo 时的 form 表单 为例 如果要生成上面的表单，需要这么填写 `data.yml` ```yml additionalProperties: #固定参数 formFields: - default: "" envKey: PANEL_DB_HOST #docker-compose 文件中的参数 key: mysql #依赖应用的 key , 例如 mysql label: en: Database Service ja: データベースサービス ms: Perkhidmatan Pangkalan Data pt-br: Serviço de Banco de Dados ru: Сервис базы данных ko: 데이터베이스 서비스 zh: 数据库服务 zh-Hant: 數據庫 服務 required: true #是否必填 type: service #如果需要依赖其他应用，例如数据库，使用此 type - default: halo envKey: PANEL_DB_NAME label: en: Database ja: データベース ms: Pangkalan Data pt-br: Banco de Dados ru: База данных ko: 데이터베이스 zh: 数据库名 zh-Hant: 資料庫名稱 random: true #是否在 default 文字后面，增加随机字符串 required: true rule: paramCommon #校验规则 type: text #需要手动填写的，使用此 type - default: halo envKey: PANEL_DB_USER label: en: User ja: ユーザー ms: Pengguna pt-br: Usuário ru: Пользователь ko: 사용자 zh: 数据库用户 zh-Hant: 資料庫使用者 random: true required: true rule: paramCommon type: text - default: halo envKey: PANEL_DB_USER_PASSWORD label: en: Password ja: パスワード ms: Kata laluan pt-br: Senha ru: Пароль ko: 비밀번호 zh: 数据库用户密码 zh-Hant: 資料庫使用者密碼 random: true required: true rule: paramComplexity type: password #密码字段使用此 type - default: admin envKey: HALO_ADMIN labelEn: Admin Username labelZh: 超级管理员用户名 required: true rule: paramCommon type: text - default: http://localhost:8080 edit: true envKey: HALO_EXTERNAL_URL label: en: External URL ja: 外部URL ms: URL Luaran pt-br: URL Externa ru: Внешний URL ko: 외부 URL zh: 外部访问地址 zh-Hant: 外部訪問地址 required: true rule: paramExtUrl type: text - default: 8080 edit: true envKey: PANEL_APP_PORT_HTTP label: en: Port ja: ポート ms: Port pt-br: Porta ru: Порт ko: 포트 zh: 端口 zh-Hant: 埠 required: true rule: paramPort type: number #端口使用此 type ``` ## 关于端口字段： `PANEL_APP_PORT_HTTP` 有 `web` 访问端口的优先使用此 `envKey` `envKey` 中包含 `PANEL_APP_PORT` 前缀会被认定为端口类型，并且用于安装前的端口占用校验。注意：端口需要是外部端口 ## 关于 type 字段： | type | 说明 | |----------|-----------------------------------------------------------------------------------------| | service | type: service 如果该应用需要依赖其他组件，如 mysql redis 等，可以通过 key: mysql 定义依赖的名称，在创建应用时会要求先创建依赖的应用。 | | password | type: password 敏感信息，如密码相关的字段会默认不显示明文。 | | text | type: text 一般内容，比如数据库名称，默认明文显示。 | | number | type: number 一般用在端口相关的配置上，只允许输入数字。 | 简单的例子 ```yml # type: service，定义一个 mysql 的 service 依赖。 - child: default: "" envKey: PANEL_DB_HOST required: true type: service default: mysql envKey: PANEL_DB_TYPE label: en: Database Service ja: データベースサービス ms: Perkhidmatan Pangkalan Data pt-br: Serviço de Banco de Dados ru: Сервис баз данных ko: 데이터베이스 서비스 zh-hant: 資料庫服務 zh: 数据库服务 required: true type: apps values: - label: MySQL value: mysql - label: MariaDB value: mariadb # type: password - default: word envKey: PANEL_DB_USER_PASSWORD labelEn: Database Password labelZh: 数据库密码 label: en: Database Password ja: データベースのパスワード ms: Kata Laluan Pangkalan Data pt-br: Senha do Banco de Dados ru: Пароль базы данных ko: 데이터베이스 비밀번호 zh-hant: 資料庫密碼 zh: 数据库密码 random: true required: true type: password # type: text - default: "" edit: true envKey: REDIS_HOST key: redis required: true type: service label: en: Redis Service ja: Redis サービス ms: Perkhidmatan Redis pt-br: Serviço Redis ru: Сервис Redis ko: Redis 서비스 zh-Hant: Redis 服務 zh: Redis 服务 # type: number - default: "" edit: true envKey: DBHUB_DB_PORT required: true type: text label: en: Database Port ja: データベースのポート ms: Pangkalan Data Port pt-br: Porta do Banco de Dados ru: Порт базы данных ko: 데이터베이스 포트 zh-hant: 資料庫端口 zh: 数据库端口 # type: select - default: "ERROR" envKey: LOG_LEVEL required: true type: select values: - label: DEBUG value: "DEBUG" - label: INFO value: "INFO" - label: WARNING value: "WARNING" - label: ERROR value: "ERROR" - label: CRITICAL value: "CRITICAL" ``` rule 字段目前支持的几种校验 | rule | 规则 | |-----------------|------------------------------------| | paramPort | 用于限制端口范围为 1-65535 | | paramExtUrl | 格式为 http(s)://(域名/ip):(端口) | | paramCommon | 英文、数字、.-和_,长度2-30 | | paramComplexity | 支持英文、数字、.%@$!&~_-,长度6-30，特殊字符不能在首尾 | 应用 `docker-compose.yml` 文件 `${PANEL_APP_PORT_HTTP} `类型的参数，都在 `data.yml` 中有声明 ```yml version: "3" services: halo: image: halohub/halo:2.2.0 container_name: ${CONTAINER_NAME} // 固定写法，勿改 restart: always networks: - 1panel-network // 1Panel 创建的应用都在此网络下 volumes: - ./data:/root/.halo2 ports: - ${PANEL_APP_PORT_HTTP}:8090 command: - --spring.r2dbc.url=r2dbc:pool:${HALO_PLATFORM}://${PANEL_DB_HOST}:${HALO_DB_PORT}/${PANEL_DB_NAME} - --spring.r2dbc.username=${PANEL_DB_USER} - --spring.r2dbc.password=${PANEL_DB_USER_PASSWORD} - --spring.sql.init.platform=${HALO_PLATFORM} - --halo.external-url=${HALO_EXTERNAL_URL} - --halo.security.initializer.superadminusername=${HALO_ADMIN} - --halo.security.initializer.superadminpassword=${HALO_ADMIN_PASSWORD} labels: createdBy: "Apps" networks: 1panel-network: external: true ``` ## 脚本 1Panel 在 安装之前、升级之前、卸载之后支持执行 .sh 脚本 分别对应 init.sh upgrade.sh uninstall.sh 存放目录(以halo为例) : halo/2.2.0/scripts # 本地测试 将应用目录上传到 1Panel 的 /opt/1panel/resource/apps/local 文件夹下 注意：/opt 为 1Panel 默认安装目录，请根据自己的实际情况修改 上传完成后，目录结构如下 ``` ├──halo ├── logo.png ├── data.yml ├── README.md ├── 2.2.0 ├── data.yml ├── data └── docker-compose.yml ``` 在 1Panel 应用商店中，点击更新应用列表按钮同步本地应用 v1.2 版本及之前版本的本地应用，请参考这个文档修改 # 提交文件 ```bash git add . git commit -m "Add my-app" git push origin dev ``` # 提交 Pull Request 在你的仓库点击 Pull requests 菜单 点击 New pull request ，填写标题和描述 选择由你的分支提交到 1Panel-dev/appstore