project.yaml 配置说明

project.yaml 是 UGOS Pro 应用的核心配置文件，用于定义应用的基本信息、运行配置、展示信息等。使用 ugcli 工具对项目进行打包时，工具会校验并根据该文件配置，生成最终的安装包。

基本配置

字段名称	类型	必填	说明
spec_version	string	是	配置规范版本，当前版本为 `2.1`
app_id	string	是	应用ID，用于系统识别应用，应用上架后不可修改。命名规范：`com.公司/组织英文名.应用名`，只能包含小写字母、数字和点，且必须以字母开头。例如：`com.mycompany.myapp`
version	string	是	应用的版本号，格式为 `x.y.z`，x为主版本号，y为次版本号，z为修订号。例如：`0.1.0`
support_arch	string[]	是	支持的 CPU 架构列表。可选值：`amd64`、`arm64`
tag_types	string[]	是	应用类别，用于应用分类展示。可选值： - `system`：系统管理 - `media`：娱乐 - `utility`：实用工具 - `security`：安全 - `download`：下载 - `backup`：备份 - `devtool`：开发工具

运行配置

字段名称	类型	必填	说明
start_cmd	string	是	应用后端服务的启动命令，包含后端服务可执行文件路径（相对于应用安装目录）和命令行参数。例如：`bin/myapp_serv --port=21010`
port	number	是	应用后端服务监听的端口号，用于提供HTTP服务。例如：`21010`
proxy_path	string	否	应用需要系统网关代理的HTTP请求路径前缀，用于将前端请求转发到后端服务。例如设置为 `api/v1`，则所有以 `/api/v1/` 开头的请求都会被转发到后端服务。
open_type	string	是	打开应用界面的方式。可选值： - `inner`：在系统桌面内以独立窗口方式打开 - `tab`：在浏览器内以新标签页方式打开
depend_fw_version	string	是	依赖的 UGOS Pro 系统最低版本。例如：`1.13.0.0000`

功能配置

字段名称	类型	必填	说明
support_migration	boolean	否	是否支持迁移安装目录。默认值：`false`
allow_add_access_path	boolean	否	是否支持用户授权访问个人文件夹和共享文件夹。默认值：`false`

权限配置

字段名称	类型	必填	说明
permissions	string[]	否	声明应用所需的系统权限列表。

支持的权限类型

权限标识	说明
SYSTEM.EXEC_SYSTEM_COMMAND	执行系统命令，可以执行系统 `/usr/bin`、`/usr/sbin` 目录下的内置命令
NETWORK.ACCESS_INTERNET	访问网络，可以创建网络连接与外部互联网服务通信

应用自定义配置 (parameters)

parameters 字段用于定义应用的自定义配置项，支持用户在安装或控制面板中的应用配置页面进行配置。

配置项结构

字段名称	类型	必填	说明
key	string	是	配置项标识，用于在应用中引用该配置
type	string	是	配置项类型。可选值： - `string`：字符串 - `number`：数字 - `path`：路径 - `password`：密码
required	boolean	否	是否必填。默认值：`false`
changeable	boolean	否	配置后是否支持再修改。默认值：`false`
multi	boolean	否	是否支持配置多个值。默认值：`false`
i18n	object	是	配置项的多语言展示信息，详见下方说明

配置项多语言 (parameters[].i18n)

字段名称	类型	必填	说明
name	string	是	配置项名称
description	string	是	配置项描述（补充说明、填写规范等）

应用展示信息多语言配置 (i18n)

i18n 字段用于定义应用的多语言展示信息。

字段名称	类型	必填	说明
name	string	是	应用显示名称
description	string	是	应用描述
author	string	是	应用开发者
official	string	否	应用官网链接
help	string	否	使用帮助网页链接
publisher	string	否	应用发布者
publisher_link	string	否	应用发布者官网链接

支持的语言：

text

en-US
zh-CN
de-DE
ja-JP
fr-FR
nl-NL
pt-PT
es-ES
it-IT
ko-KR
zh-TW

完整配置示例 (project.yaml)

yaml

# 配置规范版本
spec_version: 2.1
# 应用ID
app_id: com.mycompany.myapp
# 应用版本号
version: 0.1.0
# 支持的 CPU 架构
support_arch:
  - amd64
  - arm64
# 启动命令
start_cmd: bin/myapp_serv --port=21010
# 服务端口
port: 21010
# 代理路径前缀
proxy_path: api
# 打开方式
open_type: inner
# 应用类别
tag_types:
  - utility
  - devtool
# 依赖系统版本
depend_fw_version: 1.12.0.0000
# 支持迁移
support_migration: true
# 允许用户授权访问个人文件夹和共享文件夹
allow_add_access_path: true
# 权限声明
permissions:
  - SYSTEM.EXEC_SYSTEM_COMMAND
  - NETWORK.ACCESS_INTERNET
# 自定义参数
parameters:
  - key: ACCOUNT
    type: string
    required: true
    changeable: true
    i18n:
      en-US:
        name: Login Account
        description: 6-8 characters
      zh-CN:
        name: 登录账号
        description: 长度6-8位
# 多语言信息
i18n:
  en-US:
    name: My APP
    description: My APP Description
    author: My Company
    official: https://myapp.example.com
    help: https://myapp.example.com/help
    publisher: My Company
    publisher_link: https://mycompany.example.com
  zh-CN:
    name: 我的应用
    description: 应用描述
    author: 演示应用开发者
    official: https://myapp.example.com.cn
    help: https://myapp.example.com.cn/help
    publisher: 演示应用发布者
    publisher_link: https://mycompany.example.com.cn

project.yaml 配置说明 ​

基本配置 ​

运行配置 ​

功能配置 ​

权限配置 ​

支持的权限类型 ​

应用自定义配置 (parameters) ​

配置项结构 ​

配置项多语言 (parameters[].i18n) ​

应用展示信息多语言配置 (i18n) ​

完整配置示例 (project.yaml) ​

project.yaml 配置说明

基本配置

运行配置

功能配置

权限配置

支持的权限类型

应用自定义配置 (parameters)

配置项结构

配置项多语言 (parameters[].i18n)

应用展示信息多语言配置 (i18n)

完整配置示例 (project.yaml)