AI正在绞尽脑汁想思路ING···
BiのAI摘要
HunYuan-Lite

记录一下自己为1Panel贡献自己应用的经历

# 预准备

1. Fork仓库
   🪧引用站外地址，不保证站点的可用性和安全性
   1Panel appstore 仓库
   1panel appstore
   把仓库fork到自己的仓库
2. pull

       1
       git clone -b dev https://<your-github-username>/appstore

   创建新分支

       1
       2
       cd appstore
       git checkout -b app/<app-name>

# 创建文件

## 文件目录

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    ├──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`

本文件主要用于声明应用的一些信息

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    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`

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    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 一般用在端口相关的配置上，只允许输入数字。

简单的例子

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    # 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` 中有声明

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    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 默认安装目录，请根据自己的实际情况修改
上传完成后，目录结构如下

    1
    2
    3
    4
    5
    6
    7
    8
    ├──halo
    	├── logo.png
    	├── data.yml
    	├── README.md
    	├── 2.2.0
    	    ├── data.yml
    	    ├── data
    	    └── docker-compose.yml

在 1Panel 应用商店中，点击更新应用列表按钮同步本地应用

v1.2 版本及之前版本的本地应用，请参考这个文档修改

# 提交文件

    1
    2
    3
    git add .
    git commit -m "Add my-app"
    git push origin dev

# 提交 Pull Request

在你的仓库点击 Pull requests 菜单
点击 New pull request ，填写标题和描述
选择由你的分支提交到 1Panel-dev/appstore

文章作者: biss
文章链接: https://blog.biss.click/posts/bb18d851/
版权声明: 本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源 Bi's Blog！
1panel

评论
biss
文章
34
标签
11
分类
5
Follow Me
公告
最新文章
opencv基础操作 2026-03-15
配置opencv 2026-03-14
自建bitwarden服务 2026-02-25
自建renovate-bot 2026-02-23
新年快乐！2026-02-14
随便逛逛昼夜切换繁简转换阅读模式隐私声明 Cookie协议版权声明