GitLab Stack Config Generator

GitLab 堆栈配置生成器

此技能可为 GitLab 堆栈项目生成和管理特定于服务的配置文件，确保配置遵循正确模式、所有变量都使用 .env，且绝不包含机密信息。

何时使用此技能

在用户请求以下操作时启用此技能：

• 为服务生成配置文件（nginx、PostgreSQL、Redis 等）
• 为新服务创建配置模板
• 设置 ./config 目录结构
• 验证现有配置文件
• 确保配置正确使用 .env 变量
• 检查配置中是否包含机密信息
• 设置项目元文件（CLAUDE.md、.gitignore、.dockerignore）
• 同步 .env 和 .env.example

核心配置原则

关键规则：

1. ./env 是配置源：所有配置变量都应放在 .env 中（而非配置文件中）
2. 配置中不得包含机密信息：绝不要将机密信息放入配置文件（使用 secrets-manager）
3. 服务目录：每个服务都使用 ./config/service-name/ 目录
4. 服务目录内部保持扁平：配置文件直接放在服务目录中
5. .env 同步：.env 和 .env.example 必须始终保持一致
6. 路径验证：所有引用的路径都必须存在
7. Docker 验证：使用 docker-validation 技能验证 Docker 配置
8. 项目元文件：必须包含 CLAUDE.md、.gitignore、.dockerignore

配置工作流

阶段 1：了解需求

步骤 1：确定要生成的内容

询问用户（或根据情况推断）：

• 哪些服务需要配置？
• 是创建新配置还是更新现有配置？
• 需要生产环境、开发环境，还是两者都需要？
• 使用哪些模板（如果有）？

步骤 2：检查当前状态

1. ./config 目录是否存在？
2. .env 是否存在？
3. .env.example 是否存在？
4. 服务目录是否已存在？
5. 是否已包含元文件（CLAUDE.md、.gitignore、.dockerignore）？

阶段 2：设置目录结构

步骤 1：创建 ./config 目录

mkdir -p ./config
chmod 755 ./config

步骤 2：创建服务目录

为每个服务创建目录（例如 nginx、postgres、redis）：

mkdir -p ./config/nginx
mkdir -p ./config/postgres
mkdir -p ./config/redis
chmod 755 ./config/*

目录结构：

./config/
├── nginx/
│   ├── nginx.conf
│   ├── ssl/
│   │   └── (SSL configs, not certificates)
│   └── conf.d/
│       └── default.conf
├── postgres/
│   ├── postgresql.conf
│   └── init.sql
├── redis/
│   └── redis.conf
└── app/
    └── settings.yml

原则：

• 每个服务对应一个目录
• 每个服务目录内部采用扁平结构
• 仅在逻辑上需要时创建子目录（例如 nginx/ssl/、nginx/conf.d/）

阶段 3：生成元文件

关键：始终确保这些文件存在

步骤 1：生成 CLAUDE.md

在项目根目录中创建 CLAUDE.md：

# CLAUDE.md

This file provides guidance when working with code in this repository.

## Repository Purpose

[Brief description of the stack project]

## Stack Architecture

This is a GitLab stack project following these principles:

- **Configuration**: All variables in .env, configs in ./config
- **Secrets**: All secrets in ./secrets via Docker secrets
- **Structure**: Standard directories (./config, ./secrets, ./_temporary)
- **Docker**: Modern Docker Compose (no version field)
- **Ownership**: No root-owned files

## Working with This Stack

### Configuration Files

All service configurations are in `./config/[service-name]/` directories.
Configuration values are loaded from `.env` file.

### Environment Variables

- `.env` contains all configuration (NOT secrets)
- `.env.example` must match `.env` exactly (critical requirement)
- Update both files when adding new variables

### Secrets Management

All secrets are managed via Docker secrets:
- Location: `./secrets/` directory
- Never in .env or docker-compose.yml
- Use secrets-manager skill for secret operations

### Docker Commands

```bash
# Start stack
docker compose up -d

# View logs
docker compose logs -f

# Stop stack
docker compose down

重要规则

Git 提交

关键：创建提交消息时，绝不要在提交消息中提及“Claude”或“Claude Code”。

好的提交消息：

• “添加用于 SSL 终止的 nginx 配置”
• “更新生产环境的 PostgreSQL 设置”
• “修复 Redis 持久化配置”

不好的提交消息：

• “Claude 添加了 nginx 配置” ❌
• “请 Claude 更新设置” ❌

文件权限

所有文件都必须归当前用户所有（而非 root）：

# Check ownership
find . -user root -type f

# Fix if needed
sudo chown -R $(id -u):$(id -g) .

验证

部署前，始终运行：

# Validate entire stack
[validation command]

# Check secrets
[secrets validation command]

目录结构

./
├── docker-compose.yml      # Main compose file (NO version field)
├── .env                    # Configuration variables
├── .env.example            # Template (must match .env)
├── CLAUDE.md               # This file
├── .gitignore              # Git exclusions
├── .dockerignore           # Docker build exclusions
├── config/                 # Service configurations
│   ├── nginx/
│   ├── postgres/
│   └── redis/
├── secrets/                # Docker secrets (NOT in git)
│   └── .gitkeep
└── _temporary/             # Transient files (NOT in git)

可用技能

• stack-validator：部署前验证整个堆栈
• secrets-manager：安全管理 Docker 机密信息
• config-generator：生成或更新服务配置
• docker-validation：验证 Docker 配置

---

最后更新：[date]

**Step 2: Generate/Update .gitignore**

```gitignore
# Secrets - NEVER commit
/secrets/
/secrets/*
!secrets/.gitkeep

# Environment
.env
.env.local
.env.*.local

# Temporary
/_temporary/
/_temporary/*

# Docker
.dockerignore

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Build artifacts
dist/
build/
node_modules/
vendor/

# Backup files
*.backup
*.old
*.bak

步骤 3：生成 .dockerignore

# Git
.git/
.gitignore

# Environment
.env
.env.*

# Secrets
secrets/

# Temporary
_temporary/

# Documentation
*.md
CLAUDE.md

# IDE
.vscode/
.idea/

# OS
.DS_Store
Thumbs.db

# Dependencies (if not needed in build)
node_modules/
vendor/

# Logs
*.log
logs/

阶段 4：生成服务配置

常见服务：nginx、PostgreSQL、Redis

对于每项服务，请遵循以下模式：

步骤 1：确定配置需求

询问用户：

• 使用模板还是自定义配置？
• 启用哪些功能？
• 使用生产环境还是开发环境设置？

步骤 2：确定所需的 .env 变量

列出每项服务所需的所有 .env 变量：

nginx 示例：

• NGINX_PORT
• NGINX_HOST
• NGINX_SSL_ENABLED
• APP_HOST
• APP_PORT

步骤 3：生成配置文件

重要：使用环境变量占位符（${VAR_NAME}）

nginx.conf 示例：

# Nginx Configuration
# Loads variables from .env

upstream app {
    server ${APP_HOST}:${APP_PORT};
}

server {
    listen ${NGINX_PORT};
    server_name ${NGINX_HOST};

    # SSL configuration
    # SSL certificates loaded from Docker secrets
    # ssl_certificate /run/secrets/ssl_cert;
    # ssl_certificate_key /run/secrets/ssl_key;

    location / {
        proxy_pass http://app;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

步骤 4：更新 .env

添加所有必需的变量：

# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080

步骤 5：更新 .env.example

重要：内容必须与 .env 完全一致：

# Nginx Configuration
NGINX_PORT=80
NGINX_HOST=localhost
NGINX_SSL_ENABLED=false
APP_HOST=app
APP_PORT=8080

步骤 6：更新 docker-compose.yml

为配置添加卷挂载：

services:
  nginx:
    image: nginx:alpine
    ports:
      - "${NGINX_PORT}:80"
    volumes:
      - ./config/nginx/nginx.conf:/etc/nginx/nginx.conf:ro
    environment:
      # Variables loaded from .env automatically
      NGINX_HOST: ${NGINX_HOST}
      APP_HOST: ${APP_HOST}
      APP_PORT: ${APP_PORT}

阶段 5：配置验证

步骤 1：语法验证

针对每种配置文件类型：

Nginx：

# Test nginx config
docker run --rm -v $(pwd)/config/nginx:/etc/nginx:ro nginx:alpine nginx -t

PostgreSQL：

# Check SQL syntax
# Parse init.sql for syntax errors

Redis：

# Test redis config
docker run --rm -v $(pwd)/config/redis:/usr/local/etc/redis:ro redis:alpine redis-server --test-memory 1024

步骤 2：检测密钥（重要）

扫描所有配置文件，查找密钥：

# Check for common secret patterns
grep -r -iE "(password|secret|key|token|api_key)" ./config/

# If found, this is CRITICAL SECURITY ISSUE
# Must use secrets-manager to fix

步骤 3：路径验证

检查所有引用的路径是否存在：

1. 配置文件是否引用了其他文件？
2. docker-compose.yml 中是否有卷挂载？
3. 所有路径是否都存在？

步骤 4：.env 同步（重要）

# Extract variable names from .env
env_vars=$(grep -E "^[A-Z_]+" .env | cut -d'=' -f1 | sort)

# Extract from .env.example
example_vars=$(grep -E "^[A-Z_]+" .env.example | cut -d'=' -f1 | sort)

# Compare
diff <(echo "$env_vars") <(echo "$example_vars")

# If any difference, this is CRITICAL ERROR

步骤 5：Docker 验证

重要：使用 docker-validation 技能：

"Validate docker-compose.yml using docker-validation skill"

完成前处理所有检查结果。

阶段 6：选择模板

步骤 1：提供模板

针对 nginx、PostgreSQL、Redis，提供以下选项：

Nginx 模板：

1. 简单反向代理（默认）

   • 基本代理到后端服务
   • 不使用 SSL
   • 最简配置

2. SSL 终止

   • 启用 HTTPS
   • SSL 证书来自 Docker 密钥
   • 将 HTTP 重定向到 HTTPS

3. 静态文件 + 代理

   • 提供静态文件
   • 代理 API 请求
   • 缓存标头

4. 自定义

   • 用户提供需求
   • 生成自定义配置

PostgreSQL 模板：

1. 基础（默认）

   • 标准设置
   • 简单的 init.sql
   • 适合开发

2. 生产环境

   • 优化设置
   • 连接池
   • 性能调优

3. 带扩展

   • PostGIS、UUID 等
   • 特定于扩展的配置
   • 扩展初始化脚本

4. 自定义

   • 用户指定

Redis 模板：

1. 缓存（默认）

   • 不持久化
   • 仅使用内存
   • 速度快

2. 持久化

   • RDB 快照
   • AOF 日志
   • 数据持久性

3. 发布/订阅

   • 针对消息传递进行优化
   • 不持久化
   • 高吞吐量

4. 自定义

   • 用户需求

步骤 2：根据模板生成

根据用户的选择，生成相应配置，其中包括：

• 必需的 .env 变量
• 正确集成到 docker-compose.yml
• 说明该配置的 README 章节

阶段 7：验证报告

生成后，提供全面的报告：

📝 Configuration Generation Report
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Meta Files
✅ CLAUDE.md created
✅ .gitignore updated
✅ .dockerignore created

✅ Directory Structure
✅ ./config/nginx created
✅ ./config/postgres created
✅ ./config/redis created

📄 Generated Configurations

Nginx (Simple Reverse Proxy):
✅ ./config/nginx/nginx.conf
✅ Variables added to .env (3)
✅ .env.example synced
✅ docker-compose.yml updated
✅ Syntax validation: PASS

PostgreSQL (Basic):
✅ ./config/postgres/postgresql.conf
✅ ./config/postgres/init.sql
✅ Variables added to .env (5)
✅ .env.example synced
✅ docker-compose.yml updated

Redis (Cache):
✅ ./config/redis/redis.conf
✅ Variables added to .env (2)
✅ .env.example synced
✅ docker-compose.yml updated

🔐 Security Validation
✅ No secrets in config files
✅ All secrets in ./secrets (via secrets-manager)
✅ Configs use .env variables only

✅ Path Validation
✅ All referenced paths exist
✅ Volume mounts valid

✅ .env Synchronization
✅ .env and .env.example match (10 variables)

🐳 Docker Validation
✅ docker-compose.yml syntax valid
✅ All volume mounts exist
✅ No deprecated syntax

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Configuration generation complete!

Next Steps:
1. Review generated configurations
2. Customize as needed
3. Run: docker compose config (validate)
4. Run: docker compose up -d

特定服务模式

Nginx 配置

始终包含：

• 环境变量占位符
• 上游后端引用
• 基本安全标头
• 日志配置

绝不包含：

• 硬编码的 IP 或主机
• SSL 证书内容（使用 Docker 密钥）
• 密码或令牌

变量示例：

NGINX_PORT=80
NGINX_HOST=localhost
NGINX_WORKER_PROCESSES=auto
NGINX_WORKER_CONNECTIONS=1024
APP_BACKEND_HOST=app
APP_BACKEND_PORT=8080

PostgreSQL 配置

始终包含：

• 用于创建数据库和用户的初始化脚本
• 基本性能调优
• 连接限制
• 日志设置

绝不包含：

• 密码（使用 Docker 密钥）
• 开发环境中的生产数据库名称
• 硬编码的连接字符串

变量示例：

POSTGRES_DB=myapp_db
POSTGRES_USER=myapp_user
# POSTGRES_PASSWORD in ./secrets/db_password
POSTGRES_MAX_CONNECTIONS=100
POSTGRES_SHARED_BUFFERS=256MB

Redis 配置

始终包含：

• 持久化设置
• 内存限制
• 网络绑定

绝不包含：

• 密码（如有需要，使用 Docker 密钥）
• 硬编码的主节点/从节点 IP

变量示例：

REDIS_PORT=6379
REDIS_MAXMEMORY=256mb
REDIS_MAXMEMORY_POLICY=allkeys-lru
REDIS_SAVE_ENABLED=false

与配套技能集成

secrets-manager

调用时机：

• 在配置文件中检测到密钥 → 重要
• 需要在配置中引用密钥
• 需要 SSL 证书或私钥

docker-validation

调用时机：

• 更新 docker-compose.yml 后（始终调用）
• 完成生成前
• 用户请求验证时

stack-validator

调用时机：

• 生成完成后
• 验证整个技术栈
• 确保遵循所有模式

重要说明

• 不含密钥：绝不要将密钥放入配置文件
• .env 来源：所有配置均来自 .env
• .env 同步：.env 和 .env.example 必须保持一致
• Docker 验证：始终使用 docker-validation 技能
• CLAUDE.md 规则：必须注明提交消息中不得包含“Claude”
• 模板可选：用户可选择默认项或自定义项
• 路径验证：所有路径都必须存在

示例工作流

User: "Generate nginx and PostgreSQL configs"

1. Check current state
   - ./config missing → create it
   - .env exists
   - .env.example exists
   - CLAUDE.md missing → create it

2. Generate meta files
   - Create CLAUDE.md
   - Update .gitignore
   - Create .dockerignore

3. Ask user for templates
   "Which templates would you like?
    - Nginx: [Simple Reverse Proxy], SSL Termination, Static + Proxy, Custom
    - PostgreSQL: [Basic], Production, With Extensions, Custom"

4. User selects: Simple Reverse Proxy, Basic

5. Generate nginx config
   - Create ./config/nginx/nginx.conf
   - Add variables to .env
   - Sync .env.example
   - Update docker-compose.yml
   - Validate syntax

6. Generate PostgreSQL config
   - Create ./config/postgres/postgresql.conf
   - Create ./config/postgres/init.sql
   - Add variables to .env
   - Sync .env.example
   - Update docker-compose.yml

7. Run validations
   - Secret detection: PASS
   - Path validation: PASS
   - .env sync check: PASS
   - Docker validation (via docker-validation skill): PASS

8. Generate report
   - Show all created files
   - List .env variables added
   - Confirmation that validations passed

9. Next steps
   - Suggest testing: docker compose config
   - Recommend: docker compose up -d

---

此技能按照 GitLab 技术栈模式生成服务配置，并进行严格验证。