ugcli 使用指南

工具简介

ugcli 命令行工具，旨在为UGOS Pro系统的应用开发者提供项目创建、打包、配置生成和检查等功能。 该工具支持在 Windows、Linux 和 MacOS 系统上运行，帮助开发者快速创建和管理UGOS Pro应用项目。

下载使用

根据您的操作系统下载对应的可执行文件：

平台	架构	文件名
Linux	x86_64	ugcli-linux-amd64
Windows	x86_64	ugcli-windows-amd64.exe
macOS	x86_64	ugcli-darwin-amd64

Linux/macOS 安装

打开系统上的终端后执行如下shell命令（macOS 系统可执行文件使用 ugcli-darwin-amd64）：

# 添加执行权限
chmod +x ugcli-linux-amd64

# 重命名并移动到系统路径
sudo mv ugcli-linux-amd64 /usr/local/bin/ugcli

# 验证安装
ugcli --version

Windows 安装

1. 下载对应的 .exe 文件
2. 将文件重命名为 ugcli.exe
3. 将文件路径添加到 PATH 环境变量
4. 在终端中运行 ugcli --version 验证安装

基本命令使用

创建新项目

通过 create 子命令来创建一个新的应用项目，并通过交互式问答来配置应用的基本信息。

例如，创建一个名为 my-app 的项目：

$ugcli create my-app
Input new values for the config (press Enter to keep the current value):
? Set the application ID (e.g. com.mycompany.myapp)*: com.mycompany.myapp
? Set the version of your application (e.g. 1.0.0)*: 0.1.0
? Choose a type for your application*: utility
? Choose the architectures your application supports*: amd64, arm64
? Choose the open type for your application, inner: open in new window at desktop, tab: open in new tab at browser*: inner
? Enter the start command for your application's backend service (e.g. bin/myapp_server --port=28080)*: bin/myapp_serv --port=21010
? The port number that your application will listen on*: 21010
? The path that your application want system gateway to proxy to this port (leave empty if not needed): api
Configure your application's display information (en-US):
? Application display name*: My APP
? Application description*: My APP Desc
? Application author: nobody
? Application official website: https://myapp.example.com
? Application help website: https://myapp.example.com/help

配置项说明：

• 应用ID：应用的唯一标识，格式为 com.mycompany.myapp，用于系统识别应用，应用上架后不可修改。
• 版本号：应用的版本号，格式为 x.y.z。
• 应用类别：应用的分类，可选值： system(系统管理), media(娱乐), utility(实用工具), security(安全), download(下载), backup(备份), devtool(开发工具)。
• 支持架构：应用支持的CPU架构，可选值： amd64、arm64，支持多选。
• 打开方式：应用安装后，打开应用界面的方式，可选值：inner（在系统桌面内以独立窗口方式打开）、tab（在浏览器内以新标签页方式打开）。
• 启动命令：应用后端服务的启动命令，包含后端服务可执行文件路径（相对于应用安装目录）和命令行参数。
• 监听端口号：应用后端服务监听的端口号，用于提供HTTP服务。应用启动前，系统会检查该端口是否被占用，启动后系统会通过探测该端口来判断应用是否启动成功。
• 代理路径：应用需要系统网关代理的HTTP请求路径前缀，用于将前端请求转发到后端服务。例如设置为 api/v1，则所有以 /api/v1/ 开头的请求都会被转发到后端服务。
• 应用展示信息：应用在应用详情页中展示的信息，包含应用名称，详细描述，开发者，官方网站和帮助页面链接。支持多语言，默认配置的语言为英文，添加其他语言配置请参考多语言配置。

按提示配置完成，将在当前目录下生成 my-app 目录，包含应用配置文件project.yaml和打包需要的目录。

$tree my-app
my-app
├── project.yaml      # 应用配置文件
├── rootfs_amd64      # 应用打包目录（amd64架构）
├── rootfs_arm64      # 应用打包目录（arm64架构）
└── rootfs_common     # 应用打包目录（共用）
    ├── icon.png      # 应用图标
    └── www           # 前端静态文件目录

应用是一个典型的前后端分离应用：

• 后端服务程序需要编译成两个架构的版本，分别放在对应架构 rootfs_{amd64,arm64}/bin 目录下。
• 前端构建的html，js，css等静态文件放在www目录下，该目录在应用安装后会被映射到系统web服务器的静态资源目录下，由系统web服务器直接提供访问。
• 后端服务程序在应用安装启用后，会以后台服务的方式运行并监听指定端口，前端通过调用后端服务提供的API接口进行交互。API请求将由系统网关进行代理转发到后端服务。

如果应用自身监听的端口提供完整的web服务，不需要系统web服务器提供静态资源访问，则打开方式可以配置为 tab，用户点击桌面应用图标后，会在浏览器新标签页中直接通过IP+端口的方式访问应用。

修改项目配置

通过 config 子命令，查看与修改项目配置。

# 进入项目目录
$cd my-app

# 查看当前项目配置
$ugcli config list

# 修改项目配置（交互式），如果保持不变，直接回车
$ugcli config edit

# 新增或修改指定语言的应用描述信息（交互式）
$ugcli config edit i18n
? Choose a language to edit: zh-CN
Input new values for the config (press Enter to keep the current value):
Configure your application's display information (zh-CN):
? Application display name*: 演示应用(MY APP)
? Application description*: 演示应用描述
? Application author: 演示应用开发者
? Application official website:
? Application help website:

多语言配置

可以直接修改 project.yaml 文件中的 i18n 字段来配置多语言信息，例如：

i18n:
  en-US:
    name: My APP
    description: My APP Desc
    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

字段说明:

• name: 应用展示名称
• description: 应用描述, 会显示在应用详情页
• author: 应用开发者
• official（可选）: 应用官网链接
• help（可选）: 应用使用帮助网页链接
• publisher（可选）: 应用发布者
• publisher_link（可选）: 应用发布者官网链接

可配置的语言列表：

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

检查项目配置

通过 check 子命令，检查项目配置是否正确。

$ugcli check
Checking project in /home/example/my-app
✓ check passed

将会检查项目配置的完整性，包括：

• project.yaml 配置文件及其内容
• rootfs 目录结构

打包项目

通过 pack 子命令，将项目打包成upk格式的安装包。安装包将包含项目rootfs_common和rootfs_{arch}目录下的所有文件（同名文件以rootfs_{arch}为准），以及项目的配置信息。

# 打包当前项目
ugcli pack --arch all --build 1

参数说明：

• --build, -b: 设置构建号（整数）
• --arch, -a: 指定目标架构 (可选值：amd64/arm64/all)

更多参数和使用说明，请运行 ugcli pack --help 查看详细帮助信息。

打包完成后，会在项目的 build_dir/pkgs/upk 目录下生成一个upk格式的安装包，文件名为 {arch}_{appid}_{version}.{build}.upk。

常见问题

如何安装测试打包生成的upk包

1. 准备一台绿联NAS设备，并升级到最新版本的UGOS Pro系统。
2. 提交NAS设备的序列号，MAC地址和管理员用户名到绿联官方，申请开发者授权。
3. 将授权文件重命名为 ugdev.sig，并上传到NAS设备管理员用户的个人文件夹。
4. 在NAS设备上打开应用中心，点击手动安装，选择打包好的upk文件进行安装测试。