373 lines
12 KiB
Markdown
373 lines
12 KiB
Markdown
---
|
||
title: 为1Panel添加自己想要的应用
|
||
categories: 技术
|
||
tags: 1panel
|
||
cover: https://pic.biss.click/i/2025/08/30/m8yviz.png
|
||
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://<your-github-username>/appstore
|
||
```
|
||
创建新分支
|
||
```bash
|
||
cd appstore
|
||
git checkout -b app/<app-name>
|
||
```
|
||
# 创建文件
|
||
|
||
## 文件目录
|
||
```
|
||
├──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 |