最后更新: 2024年1月15日
配置管理
本文档介绍如何配置和管理 UnlimitBytes 应用的各项设置。
配置文件
unlimitbytes.yaml
这是主配置文件,定义应用的所有配置项:
# 应用元数据
app:
name: my-app
description: My awesome application
region: cn-shanghai
runtime: nodejs18
# 构建配置
build:
dockerfile: Dockerfile
context: .
target: production
args:
NODE_ENV: production
BUILD_VERSION: ${GIT_SHA}
cache: true
cache_from:
- registry.unlimitbytes.com/my-app:cache
# 运行时配置
runtime:
command: ["node", "dist/index.js"]
working_dir: /app
user: node
# 资源配置
resources:
requests:
cpu: 500m
memory: 256Mi
limits:
cpu: 1000m
memory: 512Mi
# 网络配置
network:
ports:
- name: http
port: 3000
protocol: TCP
ingress:
enabled: true
domain: my-app.unlimitbytes.com
tls: true
annotations:
nginx.ingress.kubernetes.io/rate-limit: "100"
# 存储配置
storage:
volumes:
- name: data
size: 10Gi
mount_path: /app/data
storage_class: ssd
- name: logs
size: 5Gi
mount_path: /app/logs
# 环境变量
env:
NODE_ENV: production
PORT: 3000
LOG_LEVEL: info
# 密钥引用
secrets:
- name: database-credentials
env:
- key: DATABASE_URL
secret_key: url
- name: api-keys
mount_path: /app/secrets
# 健康检查
health_check:
liveness:
http:
path: /health/live
port: 3000
initial_delay: 30s
period: 10s
timeout: 5s
failure_threshold: 3
readiness:
http:
path: /health/ready
port: 3000
initial_delay: 10s
period: 5s
timeout: 3s
# 自动扩缩容
autoscaling:
enabled: true
min_replicas: 2
max_replicas: 10
metrics:
- type: cpu
target: 70
- type: memory
target: 80
- type: custom
name: http_requests_per_second
target: 1000
# 部署策略
deploy:
strategy: rolling-update
max_surge: 1
max_unavailable: 0
min_ready_seconds: 10
revision_history_limit: 10
auto_rollback:
enabled: true
conditions:
- error_rate > 5%
# 日志配置
logging:
level: info
format: json
outputs:
- type: stdout
- type: file
path: /app/logs/app.log
max_size: 100Mi
max_files: 5
# 监控配置
monitoring:
metrics:
enabled: true
path: /metrics
port: 9090
tracing:
enabled: true
sampling_rate: 0.1
# 定时任务
cron_jobs:
- name: cleanup
schedule: "0 2 * * *"
command: ["npm", "run", "cleanup"]
resources:
cpu: 100m
memory: 128Mi
环境变量
设置方式
1. 配置文件
env:
NODE_ENV: production
API_TIMEOUT: 5000
FEATURE_FLAG_NEW_UI: true
2. CLI 命令
# 设置单个变量
ub env:set DATABASE_URL=postgres://... --env production
# 从文件导入
ub env:set --file .env.production
# 批量设置
ub env:set \
DATABASE_URL=postgres://... \
REDIS_URL=redis://... \
API_KEY=secret
3. Web 控制台
通过 Web 界面可视化管理环境变量。
变量优先级
从高到低:
- 运行时注入的变量
- CLI 设置的变量
- 配置文件中的变量
- Dockerfile 中的 ENV
变量引用
支持引用其他变量:
env:
APP_URL: https://my-app.com
API_URL: ${APP_URL}/api
VERSION: ${GIT_SHA:-latest} # 带默认值
密钥管理
创建密钥
# 创建密钥
ub secret:create database-credentials \
--from-literal=url=postgres://user:pass@host/db
# 从文件创建
ub secret:create tls-cert \
--from-file=tls.crt=./cert.pem \
--from-file=tls.key=./key.pem
# 从 .env 文件创建
ub secret:create env-secrets --from-env-file=.env.secret
使用密钥
作为环境变量
secrets:
- name: database-credentials
env:
- key: DATABASE_URL
secret_key: url
作为文件挂载
secrets:
- name: tls-cert
mount_path: /app/certs
items:
- key: tls.crt
path: server.crt
- key: tls.key
path: server.key
密钥轮换
# 更新密钥
ub secret:update database-credentials \
--from-literal=url=postgres://newuser:newpass@host/db
# 重启应用使用新密钥
ub restart
资源配置
CPU 和内存
resources:
requests: # 保证分配的资源
cpu: 500m
memory: 256Mi
limits: # 最大可用资源
cpu: 1000m
memory: 512Mi
单位说明:
- CPU:
1000m= 1 核心 - 内存:
256Mi= 256 MiB,1Gi= 1 GiB
存储卷
storage:
volumes:
- name: data
size: 10Gi
mount_path: /app/data
storage_class: ssd # 高性能 SSD
access_mode: ReadWriteOnce
- name: shared
size: 20Gi
mount_path: /app/shared
storage_class: nfs # 共享存储
access_mode: ReadWriteMany
临时存储
resources:
ephemeral_storage:
requests: 1Gi
limits: 5Gi
网络配置
端口映射
network:
ports:
- name: http
port: 3000
protocol: TCP
- name: grpc
port: 50051
protocol: TCP
域名和路由
network:
ingress:
enabled: true
domain: my-app.unlimitbytes.com
tls: true
rules:
- path: /api
service_port: 3000
- path: /admin
service_port: 3001
auth: true
自定义域名
# 添加自定义域名
ub domain:add www.myapp.com
# 配置 SSL 证书
ub ssl:create www.myapp.com --auto
# 验证域名
ub domain:verify www.myapp.com
数据库配置
PostgreSQL
databases:
- name: main-db
type: postgres
version: 15
resources:
cpu: 1000m
memory: 1Gi
storage: 20Gi
backup:
enabled: true
schedule: "0 3 * * *"
retention: 7d
Redis
caches:
- name: session-cache
type: redis
version: 7
mode: cluster
replicas: 3
resources:
memory: 512Mi
persistence: true
连接配置
env:
DATABASE_URL: ${database.main-db.url}
REDIS_URL: ${cache.session-cache.url}
配置验证
语法检查
# 验证配置文件
ub config:validate
# 查看解析后的配置
ub config:show
# 对比环境配置
ub config:diff --env staging --env production
配置模板
使用模板简化配置:
# config/base.yaml
app:
name: my-app
runtime: nodejs18
---
# config/production.yaml
extends: ./base.yaml
resources:
cpu: 2000m
memory: 1Gi
autoscaling:
enabled: true
min_replicas: 3
max_replicas: 10
配置最佳实践
1. 环境分离
为不同环境维护独立配置:
config/
├── base.yaml # 基础配置
├── development.yaml # 开发环境
├── staging.yaml # 测试环境
└── production.yaml # 生产环境
2. 密钥安全
- 永远不要将密钥提交到代码仓库
- 使用密钥管理系统存储敏感信息
- 定期轮换密钥
- 限制密钥访问权限
3. 资源规划
# 开发环境 - 最小资源
resources:
cpu: 100m
memory: 128Mi
# 生产环境 - 充足资源
resources:
requests:
cpu: 500m
memory: 512Mi
limits:
cpu: 2000m
memory: 2Gi
4. 版本控制
app:
version: ${GIT_TAG}
env:
APP_VERSION: ${GIT_TAG}
BUILD_TIME: ${BUILD_TIMESTAMP}
GIT_COMMIT: ${GIT_SHA}
故障排查
配置问题诊断
# 查看当前配置
ub config:show
# 查看环境变量
ub env:list
# 查看密钥列表(不显示值)
ub secret:list
# 检查资源使用
ub metrics
# 查看事件日志
ub events --type ConfigError
常见问题
配置未生效:
# 重新加载配置
ub config:reload
# 重启应用
ub restart
资源不足:
# 增加资源限制
ub resources:update --cpu 2000m --memory 2Gi
# 检查节点资源
ub cluster:resources