服务器YAML配置要注意什么

编写服务器 YAML 配置时，核心在于保证缩进正确、结构清晰、敏感信息隔离，并遵循“环境隔离”与“版本控制”原则。以下是关键注意事项及最佳实践：

一、基础语法与格式

1. 缩进规则

   • 必须使用空格，禁止使用 Tab（多数解析器会报错）。
   • 推荐 2 个空格 作为缩进单位（行业标准）。

   server:
     port: 8080  # 正确
   

2. 键值对格式

   • 冒号后必须有空格：key: value ✅，key:value ❌。
   • 字符串通常无需引号，但含特殊字符（:、#、空格）时需加引号：

     path: "/data/logs:backup"  # 必须加引号
     

3. 列表写法

   • 短横线后必须有空格：

     ports:
       - 80
       - 443
     

二、敏感信息与安全性

1. 禁止硬编码密码、Token

   • 使用环境变量或密钥管理工具（Vault、KMS）：

     # 错误示例
     password: "123456"
     
     # 正确示例
     password: ${DB_PASSWORD}  # 从环境变量读取
     

   • Spring Boot 等框架支持 ${} 占位符。

2. 文件权限控制

   • 配置文件权限设为 600（仅 owner 可读），避免泄露。

三、环境隔离与配置管理

1. 多环境分离

   • 按环境拆分文件，避免单一文件臃肿：

     config/
       application-dev.yaml
       application-prod.yaml
     

   • 通过启动参数指定环境：--spring.profiles.active=prod。

2. 避免配置漂移

   • 生产配置禁止随意修改，变更需走 CI/CD 流程。

四、可读性与维护性

1. 添加注释

   • 复杂配置项必须注释说明用途：

     # 连接池最大活跃数（根据服务器内存调整）
     maxActive: 50
     

2. 逻辑分组

   • 按功能模块组织配置，避免平铺：

     database:
       host: localhost
       port: 3306
     cache:
       redis:
         host: 127.0.0.1
     

3. 使用锚点（Anchor）减少重复

   • 适合重复配置片段（如多服务相同超时设置）：

     defaults: &defaults
       timeout: 30s
       retry: 3
     
     service1:
       <<: *defaults  # 继承 defaults
     

五、验证与工具

1. 语法检查

   • 使用在线工具（如 YAML Lint）或 IDE 插件（VS Code 的 YAML 插件）实时校验。

2. 结构化验证

   • 对 Kubernetes 等配置，使用 kubectl --dry-run=client -f config.yaml 预检。

3. 版本控制

   • 配置文件纳入 Git，但排除敏感文件（.gitignore 中添加 *.secret.yaml）。

六、常见陷阱与避坑

七、框架特定建议

• Spring Boot：
  • 使用 application.yaml 而非 properties，层级更清晰。
  • 支持多文档块（--- 分隔）在一个文件内定义多环境，但生产环境仍建议分文件。
• Kubernetes：
  • 使用 ConfigMap/Secret 分离配置与镜像。
  • 避免直接写 latest 镜像标签，明确版本号。

总结

编写服务器 YAML 时，牢记：

1. 格式零错误（缩进、空格、引号）。
2. 安全第一位（无明文密码、权限控制）。
3. 环境要隔离（dev/test/prod 分离）。
4. 维护要简单（注释、分组、锚点）。

遵循这些原则，可大幅减少因配置导致的服务器故障。