ljwx-tiny/VARIABLES.md

变量字典 (Variables Dictionary)

目标

本文件详细说明 ljwx-template 中所有配置变量的定义、含义、默认值和使用规则。这是确保模板一致性和减少变量漂移的关键文档。

变量映射关系

ljwx.yaml (单一事实源)

项目基本信息

字段	类型	必需	默认值	描述	映射到
appName	string	✅	-	应用名称	Helm Release Name, Namespace, ConfigMap Key
stack	string	✅	-	技术栈	springboot | fastapi | vue3
namespace	string	✅	-	Kubernetes 命名空间	K8s namespace, ArgoCD destination

镜像配置

字段	类型	必需	默认值	描述	映射到
image.repo	string	✅	-	镜像仓库地址	Helm .Values.image.repository
image.tag	string	✅	latest	镜像标签	Helm .Values.image.tag

域名配置

字段	类型	必需	默认值	描述	映射到
domain.host	string	✅	-	访问域名	Helm .Values.ingress.host
domain.tlsSecret	string	✅	-	TLS 证书 Secret 名称	Helm .Values.ingress.tlsSecretName

运行时配置

字段	类型	必需	默认值	描述	映射到
profile	string	✅	docker	运行时配置文件	Spring Profile / FastAPI 环境变量
port	int	✅	8080 / 8000 / 80	服务端口	根据 stack 自动映射到对应容器端口

数据库配置 (仅 Spring Boot)

字段	类型	必需	默认值	描述	映射到
infra.mysqlSecret	string	✅ (仅 springboot)	-	MySQL 连接 Secret 名称	Helm .Values.infra.mysql.secretName

Redis 配置 (仅 Spring Boot)

字段	类型	必需	默认值	描述	映射到
infra.redisSecret	string	✅ (仅 springboot)	-	Redis 连接 Secret 名称	Helm .Values.infra.redis.secretName

ljwx.yaml → Helm values 映射

Spring Boot 映射示例

# ljwx.yaml
appName: bookstore
stack: springboot
image:
  repo: harbor.omniverseai.net:8080/ljwx/ljwx-bookstore
  tag: latest
domain:
  host: book.omniverseai.net
  tlsSecret: book-tls
profile: docker
port: 8080
infra:
  mysqlSecret: bookstore-mysql-secret
  redisSecret: bookstore-redis-secret

映射到 helm/values.yaml:

app:
  springProfile: docker
  
image:
  repository: harbor.omniverseai.net:8080/ljwx/ljwx-bookstore
  tag: latest

ingress:
  host: book.omniverseai.net
  tlsSecretName: book-tls

service:
  port: 8080

infra:
  mysql:
    secretName: bookstore-mysql-secret
  redis:
    secretName: bookstore-redis-secret

FastAPI 映射示例

# ljwx.yaml
appName: api-service
stack: fastapi
image:
  repo: harbor.omniverseai.net:8080/ljwx/ljwx-fastapi
  tag: latest
domain:
  host: api.omniverseai.net
  tlsSecret: api-tls
profile: prod
port: 8000

映射到 helm/values.yaml:

image:
  repository: harbor.omniverseai.net:8080/ljwx/ljwx-fastapi
  tag: latest

ingress:
  host: api.omniverseai.net
  tlsSecretName: api-tls

service:
  port: 8000

Vue3 映射示例

# ljwx.yaml
appName: web-frontend
stack: vue3
image:
  repo: harbor.omniverseai.net:8080/ljwx/ljwx-web
  tag: latest
domain:
  host: web.omniverseai.net
  tlsSecret: web-tls
profile: prod
port: 80

映射到 helm/values.yaml:

image:
  repository: harbor.omniverseai.net:8080/ljwx/ljwx-web
  tag: latest

ingress:
  host: web.omniverseai.net
  tlsSecretName: web-tls

service:
  port: 80

ljwx.yaml → .env 映射

Spring Boot 映射

APP_NAME=bookstore
STACK=springboot
IMAGE_REPO=harbor.omniverseai.net:8080/ljwx/ljwx-bookstore
IMAGE_TAG=latest
DOMAIN_HOST=book.omniverseai.net
TLS_SECRET=book-tls
PROFILE=docker
PORT=8080
MYSQL_SECRET=bookstore-mysql-secret
REDIS_SECRET=bookstore-redis-secret

FastAPI 映射

APP_NAME=api-service
STACK=fastapi
IMAGE_REPO=harbor.omniverseai.net:8080/ljwx/ljwx-fastapi
IMAGE_TAG=latest
DOMAIN_HOST=api.omniverseai.net
TLS_SECRET=api-tls
PROFILE=prod
PORT=8000

Vue3 映射

APP_NAME=web-frontend
STACK=vue3
IMAGE_REPO=harbor.omniverseai.net:8080/ljwx/ljwx-web
IMAGE_TAG=latest
DOMAIN_HOST=web.omniverseai.net
TLS_SECRET=web-tls
PORT=80

变量命名规则

环境变量命名

• 所有环境变量使用大写字母和下划线
• 前缀统一，避免冲突

Helm Values 命名

• 使用小写字母和驼峰命名
• 保持层级结构清晰

变量添加原则

新增变量规则

1. 必须先更新此文档: 任何新变量必须在此文档中定义
2. 向后兼容: 确保现有项目不受影响
3. 最小必要: 只添加确实必要的变量
4. 明确默认值: 为每个变量提供合理的默认值

禁止事项

• ❌ 不允许在代码中硬编码配置
• ❌ 不允许在模板中添加不使用的变量
• ❌ 不允许绕过 ljwx.yaml 直接写入配置文件

技术栈特定变量

Spring Boot 特有变量

• Flyway 数据库迁移相关配置
• Spring Profile 配置
• 数据库和 Redis 连接配置

FastAPI 特有变量

• Python 虚拟环境配置
• Uvicorn 服务器配置
• 数据库连接配置 (如启用)

Vue3 特有变量

• 前端构建工具配置 (npm/pnpm/yarn)
• Vite 运行时配置
• 客户端 API 基础路径

验证规则

变量完整性检查

1. ljwx.yaml 中的每个字段都必须在映射表中有定义
2. 所有必需字段都必须存在于 ljwx.yaml 中
3. 所有环境变量都必须有对应的来源

更新流程

1. 任何变量更新都必须先更新此文档
2. 提交 PR 时必须说明变量变更的影响
3. 确保模板和验证脚本能正确处理新变量