biss/blog
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

update

Browse Source
This commit is contained in:
biss
2025-08-19 11:09:19 +08:00
parent d4fc785aba
commit bb16e0c7e4
2 changed files with 373 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

372
source/_posts/add-own-app-to-1panel.md Normal file
View File

@@ -0,0 +1,372 @@
---
title: 为1Panel添加自己想要的应用
categories: 技术
tags: 1panel
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