diff --git a/docs/app-example-python-description.md b/docs/app-example-python-description.md index 3a148b20745a8fa132be469ae298fb5374bb7d7b..4a40e52ecceae15b73a4a983bf42b490b2250339 100644 --- a/docs/app-example-python-description.md +++ b/docs/app-example-python-description.md @@ -17,6 +17,7 @@ lzc-manifest.yml 是控制应用 Meta 信息的配置文件。 - `license`: 应用的发行许可证 - `homepage`: 项目主页 - `author`: 作者信息 +- `deploy_params`: 指定应用启动配置文件 这个文件最重要的是 `application` 字段： @@ -204,3 +205,200 @@ services: #传统docker镜像启动方式，如果需要数据库等配套容器 ## 保存数据的路径 当后端需要存储文件或者数据库时， 请确保文件放在 `/lzcapp/var`​ 目录下， 存在其他目录下的文件会在应用 Docker 重启后被系统清空。 + + + +## lzc-manifest.yml使用模板变量 + +`manifest.yml` 支持模板变量，提升配置灵活性。 + +变量列表： + +* **SysParams** 别名 **S** + +**SysParams**是一个 `map[string]string` 类型变量 ，其拥有值如下： + +``` +BoxDomain 微服域名 +BoxName 微服名称 +IsMultiInstance 实际的部署方式 +DepolyUID 如果是多实例，则为当前部署UID +AppDomain 应用域名 + +``` + +使用： +``` +{{ .SysParams.BoxName }} +{{ .S.BoxName}} +``` + +示例： +``` +services: + db: + image: xxxx + environment: + - BOXNAME={{.S.BoxName}} + - BOXDOMAIN={{.S.BoxDomain}} +``` + +* **UserParams** 别名 **U** + +**UserParams**是 用户填写 `deploy_params` 表单值。详情请阅读 [DeployParams配置](#deployparams配置) + +示例： + +`deploy_params.yml`: +``` +user_deploy_params: + - id: user_id + type: lzc_uid + description: 微服用户ID + hidden: true + - id: db_user + type: string + description: 数据库用户名 + default_value: root + optional: true + hidden: false + - id: db_passwd + type: string + description: 数据库密码 + default_value: {{ random 16 }} + hidden: true +``` + +使用： +``` +{{.UserParams.user_id}} +{{.UserParams.db_user}} +{{.UserParams.db_passwd}} +{{.U.user_id}} +{{.U.db_user}} +{{.U.db_passwd}} +``` + +示例： +``` +services: + db: + image: registry.lazycat.cloud/vim/library/mariadb:04d70a5a9b401d15 + environment: + - MARIADB_ROOT_PASSWORD={{.U.db_passwd}} + - MARIADB_DATABASE={{.U.db_user}} +``` + +* **Manifest** 别名 **M** + +**Manifest**是对应`manifest.yml`文件解析的对象。 + +注：此**Manifest**是`manifest.yml`渲染前的对象，所以其中值会出现原始的模板变量占位符。 + +**Manifest** 数据结构 +```go +type ManifestConfig struct { + Package string `yaml:"package"` + Version string `yaml:"version"` + Name string `yaml:"name"` + Description string `yaml:"description"` + Usage string `yaml:"usage"` + License string `yaml:"license"` + Homepage string `yaml:"homepage"` + Author string `yaml:"author"` + Permissions []string `yaml:"permissions"` + RuntimeDependencies struct { + // 懒猫云系统的约束 + OS string `yaml:"os"` + // hclient的版本约束 + Client string `ymal:"client"` + }`yaml:"runtime_dependencies"` + UnsupportedPlatforms []string `yaml:"unsupported_platforms"` + Application struct { + Image string `yaml:"image"` + DependsOn []string `yaml:"depends_on"` + BackgroundTask bool `yaml:"background_task"` + Subdomain string `yaml:"subdomain"` + USBAccel bool `yaml:"usb_accel"` + GpuAccel bool `yaml:"gpu_accel"` + KVMAccel bool `yaml:"kvm_accel"` + FileHandler FileHandlerConfig `yaml:"file_handler"` + Handlers HandlersConfig `yaml:"handlers"` + Routes []string `yaml:"routes"` + Workdir string `yaml:"workdir"` + PublicPath []string `yaml:"public_path"` + AuthCallback string `yaml:"authcallback"` + Ingress []IngressConfig `yaml:"ingress"` + TODO_REMOVE_UserApp bool `yaml:"user_app"` + MultiInstance bool `yaml:"multi_instance"` + Environment []string `yaml:"environment"` + HealthCheck HealthCheckConfig `yaml:"health_check"` + }`yaml:"application"` + Services map[string]struct{ + Image string `yaml:"image"` + Environment []string `yaml:"environment"` + Binds []string `yaml:"binds"` + Entrypoint *string `yaml:"entrypoint,omitempty"` + Command *string `yaml:"command,omitempty"` + Tmpfs types.StringList `yaml:"tmpfs,omitempty" json:"tmpfs,omitempty"` + DependsOn []string `yaml:"depends_on,omitempty"` + Restart *string `yaml:"restart"` + HealthCheck HealthCheckConfig `yaml:"health_check"` + NetworkMode string `yaml:"network_mode"` + NetAdmin bool `yaml:"netadmin"` + CPUShares int64 `yaml:"cpu_shares"` + CPUS float32 `yaml:"cpus"` + User string `yaml:"user,omitempty"` + } `yaml:"services"` + ExtConfig ExtConfig `yaml:"ext_config"` +} +``` + +在`manifest.yml`中使用： +``` +{{.Manifest.Name}} +{{.Manifest.Version}} +{{.M.Name}} +{{.M.Version}} +``` + +## DeployParams配置 + +懒猫微服支持在应用启动时填写应用配置。应用配置不完整时，需要用户在启动应用时通过填写Setup界面上的表单以补全应用自定义的配置，即可启动。在 `manifest.yml` 配置文件中，可通过 `{{ .UserParams.var_name }}` 进入引用配置文件。 + +![DeployParams配置界面](./public/need_setup_page.png) + +在 `lzc-build.yml` 配置中，指定 `deploy_params` 对应文件为应用配置文件，即可将 `./deploy_params.yml`打包到LPK文件中。 + +```yaml +deploy_params: ./deploy——params.yml +``` + +自定义的配置需要添加到deploy_params.yml 的user_deploy_params数组中。 下面是关于user_deploy_params 数组**项**字段解释： + + - id: 变量名 + - type: 变量类型，只支持填写 `string` `lzc_uid` `bool` + - description: 变量介绍 + - default_value: 变量默认值。注：`lzc_uid `类型下默认值无效 + - optional: 可选项， 默认值为 `false` 强制用户填写值，不填写将无法完成应用启动引导，反之则不强制填写 + - hidden: 是否隐藏该项，默认值为 `false` 表示不隐藏，建议配合 `default_value: {{random 32}}` 使用。注： `hidden` 为 `true`, `default_vaule` 为空，应用将无法完成初始化 + +`./deploy-params.yml` 文本配置示例。 + +```yaml +user_deploy_params: + - id: nickname + type: string # 合法的微服账户 + description: 引号 + optional: true + default_value: "{{ random 5 }}" + - id: box_user + type: lzc_uid + description: 微服用户名 + - id: pswd + type: string + description: 密码 + default_value: "{{ random 64 }}" + optional: false +``` + diff --git a/docs/public/need_setup_page.png b/docs/public/need_setup_page.png new file mode 100644 index 0000000000000000000000000000000000000000..a2e442ddb093d89c23b8387b92e52301b004196f Binary files /dev/null and b/docs/public/need_setup_page.png differ