幻的小屋

【AI生成】学霸笔记：25｜Claude Code ops-claude 项目说明

蛋蛋 2026年04月10日 4 0

ops-claude 项目说明

1. 项目背景

ops-claude 用于 CDN 加速运维、Nginx 配置维护、告警维护、项目配置管理、小脚本管理、发布脚本与回滚脚本管理。

本项目目标是通过统一模板、统一参数、统一规范的方式，提升运维脚本和配置管理效率，并结合 Claude Code 实现标准化生成、修改和维护。

适用场景：

  • 新产品接入
  • Nginx 配置生成与调整
  • 告警规则维护
  • 项目配置统一管理
  • 发布脚本生成
  • 回滚脚本生成
  • 巡检与健康检查脚本维护
  • 运维文档集中管理

2. 项目名称与目录位置

项目名称：

ops-claude

建议目录位置：

D:\ops-claude

说明：

  • 建议统一放在 D 盘根目录下
  • 路径尽量避免空格
  • 项目根目录可作为 Claude Code 的工作目录
  • Windows 10 下推荐使用 VS Code、PowerShell、Git Bash、WSL 配合维护

3. 为什么建议统一放在一个项目里

当前阶段，建议将以下内容统一放在一个项目中维护：

  • 告警维护
  • 项目配置
  • 小脚本
  • nginx 配置模板
  • 发布脚本
  • 回滚脚本
  • 健康检查脚本
  • 产品参数配置
  • 运维规范文档

原因如下：

  1. 同一批维护人员管理，适合集中维护
  2. 同一产品的配置、脚本、告警经常联动修改
  3. 统一参数更容易复用，减少重复配置
  4. Claude Code 在同一项目内读取上下文更完整
  5. Git 管理、审计、回滚更方便

4. 什么时候再考虑拆分项目

当前建议先统一管理，只有在以下情况下再考虑拆分：

  1. 权限隔离要求明显不同
  2. 维护团队完全不同
  3. 发布节奏差异很大
  4. 仓库规模膨胀明显
  5. 某一类资产已发展为独立平台

当前阶段建议先采用单项目统一管理方式。

5. 推荐目录结构

D:\ops-claude
├── 项目说明.md
├── README.md
├── .claude
│   ├── context.md
│   ├── rules.md
│   └── commands.md
├── docs
│   ├── 运维规范.md
│   ├── 告警维护规范.md
│   ├── 发布流程.md
│   ├── 回滚流程.md
│   └── 产品接入说明.md
├── templates
│   ├── nginx
│   │   └── base-nginx.conf
│   ├── alerts
│   │   └── base-alert-rule.yaml
│   └── shell
│       ├── deploy.sh.tpl
│       ├── rollback.sh.tpl
│       └── healthcheck.sh.tpl
├── products
│   ├── product-a
│   │   ├── product.yaml
│   │   ├── nginx
│   │   ├── alerts
│   │   └── scripts
│   └── product-b
│       ├── product.yaml
│       ├── nginx
│       ├── alerts
│       └── scripts
├── scripts
│   ├── generate_nginx.sh
│   ├── generate_alert.sh
│   ├── validate.sh
│   └── deploy.sh
└── shared
    ├── contacts.yaml
    ├── environments.yaml
    └── common-vars.yaml

6. 目录说明

6.1 项目根目录

用于统一管理本项目所有文档、模板、配置和脚本。

6.2 .claude

用于存放 Claude Code 的项目上下文和规则。

包含文件：

  • context.md：项目背景说明
  • rules.md：Claude Code 执行规则
  • commands.md：常见任务说明

6.3 docs

用于存放运维规范、告警维护规范、发布流程、回滚流程、产品接入说明等文档。

6.4 templates

用于存放标准模板，包括：

  • nginx 配置模板
  • 告警规则模板
  • shell 脚本模板

6.5 products

每个产品一个目录，按产品维度维护：

  • 产品参数配置
  • nginx 配置
  • 告警规则
  • 产品脚本

6.6 scripts

通用工具脚本目录，用于批量生成和校验配置。

6.7 shared

共享配置目录，用于统一维护联系人、环境变量、公共参数。

7. 管理原则

7.1 统一仓库管理

当前阶段采用单仓库统一管理方式，避免参数分散、重复配置和上下文割裂。

7.2 模板优先

所有新脚本、新配置优先基于 templates 目录生成，不建议从零开始手写。

7.3 参数驱动

不同产品之间的差异，统一通过 products//product.yaml 管理。

7.4 生成产物需审核

Claude Code 生成的 nginx 配置、告警规则、shell 脚本，必须经过人工审核后再发布。

7.5 发布前先校验

所有 nginx 配置变更必须先通过 nginx -t。
所有 shell 脚本需进行语法和逻辑检查。
所有告警规则应先在测试环境验证。

7.6 可回滚

配置与脚本修改应具备备份和回滚能力。

8. Windows 10 上的使用建议

8.1 推荐路径

项目统一放置于：

D:\ops-claude

8.2 推荐工具

建议安装以下工具：

  • VS Code
  • Git for Windows
  • PowerShell
  • Git Bash
  • WSL（推荐，用于 shell 脚本测试）

8.3 路径要求

  • 路径尽量不要带空格
  • 目录名尽量使用英文
  • 文档可使用中文文件名
  • 项目不建议放在桌面或下载目录

8.4 换行符要求

shell、yaml、conf 文件建议统一使用 LF 换行，避免在 Linux 环境执行异常。

8.5 使用方式建议

  • Windows 本地负责编辑、管理、提交
  • Linux/WSL 环境负责脚本测试与配置验证
  • 远程 Linux 服务器负责正式部署

具体操作执行-小白模式

你要做的事情，只有 3 步

第 1 步：先创建一个脚本文件

在电脑里新建这个文件：

D:\ops-claude\init.ps1

如果 D:\ops-claude 还没有，你先建这个文件夹。

第 2 步：把我下面给你的全部内容，完整复制进去

也就是：

  • 打开 D:\ops-claude\init.ps1
  • 把里面原有内容清空
  • 把下面这整段 PowerShell 脚本全部复制进去
  • 保存

第 3 步：运行这个脚本

打开 PowerShell，执行这一条命令：

powershell -ExecutionPolicy Bypass -File D:\ops-claude\init.ps1

执行完成后，D:\ops-claude 下面的目录和文件就会自动创建好。

最简单操作案例

方法一：用记事本

1）按 Win + R

输入：

notepad

点回车。

2）把下面这段命令复制进去，编码选择：UTF8-BOM编码

3）点击“文件” -> “另存为”

保存到：

D:\init.ps1

保存类型选择：

所有文件

编码如果能选，选：

UTF-8

4）然后按 Win + R

输入：

powershell

回车。

5）在 PowerShell 里粘贴执行：

下面为文件开头

$ErrorActionPreference = "Stop"

[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
$OutputEncoding = New-Object System.Text.UTF8Encoding($false)

$base = "D:\ops-claude"

if (Test-Path -LiteralPath $base) {
    Remove-Item -LiteralPath $base -Recurse -Force
}

$dirs = @(
    "$base",
    "$base\.claude",
    "$base\docs",
    "$base\templates",
    "$base\templates\nginx",
    "$base\templates\alerts",
    "$base\templates\shell",
    "$base\products",
    "$base\products\product-a",
    "$base\products\product-a\nginx",
    "$base\products\product-a\alerts",
    "$base\products\product-a\scripts",
    "$base\products\product-b",
    "$base\products\product-b\nginx",
    "$base\products\product-b\alerts",
    "$base\products\product-b\scripts",
    "$base\scripts",
    "$base\shared"
)

foreach ($dir in $dirs) {
    New-Item -ItemType Directory -Force -Path $dir | Out-Null
}

function Write-Utf8BomFile {
    param(
        [string]$Path,
        [string]$Content
    )
    $utf8Bom = New-Object System.Text.UTF8Encoding($true)
    [System.IO.File]::WriteAllText($Path, $Content, $utf8Bom)
}

$projectDescription = @'
# ops-claude 项目说明

ops-claude 是一个用于统一管理 CDN 运维、Nginx 配置、告警规则、项目参数、小脚本、发布脚本、回滚脚本、健康检查脚本与运维规范文档的项目。

## 目录结构

D:\ops-claude
├── 项目说明.md
├── README.md
├── .claude
│   ├── context.md
│   ├── rules.md
│   └── commands.md
├── docs
│   ├── 运维规范.md
│   ├── 告警维护规范.md
│   ├── 发布流程.md
│   ├── 回滚流程.md
│   └── 产品接入说明.md
├── templates
│   ├── nginx
│   │   └── base-nginx.conf
│   ├── alerts
│   │   └── base-alert-rule.yaml
│   └── shell
│       ├── deploy.sh.tpl
│       ├── rollback.sh.tpl
│       └── healthcheck.sh.tpl
├── products
│   ├── product-a
│   │   ├── product.yaml
│   │   ├── nginx
│   │   ├── alerts
│   │   └── scripts
│   └── product-b
│       ├── product.yaml
│       ├── nginx
│       ├── alerts
│       └── scripts
├── scripts
│   ├── generate_nginx.sh
│   ├── generate_alert.sh
│   ├── validate.sh
│   └── deploy.sh
└── shared
    ├── contacts.yaml
    ├── environments.yaml
    └── common-vars.yaml


## 管理原则

1. 模板优先
2. 参数驱动
3. 生成产物需人工审核
4. 发布前先校验
5. 变更需可回滚

## Claude Code 使用建议

建议优先阅读：
- 项目说明.md
- .claude/context.md
- .claude/rules.md
- products/<product>/product.yaml
- templates/相关模板文件
'@

$readme = @'
# ops-claude

统一管理 CDN 运维、Nginx 配置、告警规则、项目配置、小脚本、发布脚本、回滚脚本与产品参数的运维项目。

详细说明请见：
- 项目说明.md
'@

$context = @'
# 项目上下文

ops-claude 是一个用于 CDN 运维、告警维护、Nginx 配置管理、脚本生成与维护的统一项目。

项目采用单仓库统一管理方式。
每个产品的配置差异通过 products/<product>/product.yaml 管理。

Claude Code 在生成脚本和配置时，应优先读取：
1. 项目说明.md
2. .claude/rules.md
3. 对应模板文件
4. 对应产品参数文件
'@

$rules = @'
# Claude Code 规则

1. 全程中文回复
2. 任何写操作前必须说明意图
3. 优先复用 templates 目录中的模板
4. 不允许直接覆盖生产配置而不提示备份
5. shell 脚本必须包含 set -euo pipefail
6. nginx 配置变更后必须建议执行 nginx -t
7. 不允许生成危险删除命令
8. 生成内容必须尽量参数化，便于复用
9. 涉及生产发布时，必须提示先在测试环境验证
10. 涉及告警配置时，必须保留通知组和阈值说明
'@

$commands = @'
# 常见任务

## 1. 生成某产品 nginx 配置
请阅读：
- @项目说明.md
- @templates/nginx/base-nginx.conf
- @products/product-a/product.yaml

基于以上内容生成 product-a 的 nginx 配置，
输出到 @products/product-a/nginx/default.conf。

## 2. 生成某产品告警规则
请阅读：
- @项目说明.md
- @templates/alerts/base-alert-rule.yaml
- @products/product-a/product.yaml
- @shared/contacts.yaml

基于以上内容生成 product-a 的告警规则，
输出到 @products/product-a/alerts/rule.yaml。

## 3. 生成某产品部署脚本
请阅读：
- @项目说明.md
- @templates/shell/deploy.sh.tpl
- @products/product-a/product.yaml

基于以上内容生成部署脚本到：
@products/product-a/scripts/deploy.sh
'@

$opsSpec = @'
# 运维规范

## 1. 通用原则
1. 所有配置变更必须可追踪
2. 所有脚本变更必须可回滚
3. 所有生产发布必须先测试验证
4. 变更前应备份旧配置
5. 生产环境禁止直接做高风险删除操作

## 2. shell 脚本规范
1. 必须使用 bash
2. 开头必须包含：
   set -euo pipefail
3. 支持 --dry-run 优先

## 3. nginx 配置规范
1. 修改后必须先执行 nginx -t
2. reload 前必须确保语法通过
3. 配置中应保留日志定义
'@

$alertSpec = @'
# 告警维护规范

## 1. 原则
1. 每个产品单独维护告警规则
2. 告警阈值尽量从 product.yaml 读取
3. 通知组统一从 shared/contacts.yaml 维护
4. 告警名称应包含产品名和指标名
'@

$releaseFlow = @'
# 发布流程

1. 确认变更内容
2. 备份旧配置
3. 生成新配置或新脚本
4. 执行校验
5. 测试环境验证
6. 人工审核
7. 正式发布
8. 发布后健康检查
9. 如有异常执行回滚
'@

$rollbackFlow = @'
# 回滚流程

1. 确认异常范围
2. 定位对应变更
3. 使用备份配置或回滚脚本恢复
4. 再次执行校验
5. 恢复服务
6. 验证业务状态
7. 记录回滚原因
'@

$productOnboarding = @'
# 产品接入说明

## 1. 新增产品目录
在 products 下创建新目录，例如：
products/product-a/

## 2. 新增产品参数
创建：
products/product-a/product.yaml

## 3. 基于模板生成内容
可生成：
- nginx 配置
- 告警规则
- 部署脚本
- 回滚脚本
- 健康检查脚本
'@

$contacts = @'
groups:
  ops-team:
    email:
      - ops@example.com
    webhook: "https://example.com/webhook/ops-team"

  cdn-team:
    email:
      - cdn@example.com
    webhook: "https://example.com/webhook/cdn-team"
'@

$environments = @'
environments:
  dev:
    description: "开发环境"
  test:
    description: "测试环境"
  prod:
    description: "生产环境"
'@

$commonVars = @'
defaults:
  nginx_access_log_dir: "/var/log/nginx"
  nginx_error_log_dir: "/var/log/nginx"
  default_client_max_body_size: "10M"
  default_proxy_read_timeout: 60
  default_proxy_connect_timeout: 60
'@

$nginxTemplate = @'
server {
    listen 80;
    server_name example.com;

    access_log /var/log/nginx/access.log;
    error_log  /var/log/nginx/error.log warn;

    client_max_body_size 10M;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_connect_timeout 60s;
        proxy_read_timeout 60s;
    }
}
'@

$alertTemplate = @'
alert_rule:
  name: "example-latency-alert"
  product: "example-product"
  environment: "prod"
  metric: "latency_ms"
  operator: ">"
  threshold: 300
  duration: "5m"
  severity: "warning"
  notify_group: "ops-team"
  summary: "接口延迟超过阈值"
  description: "请检查回源、上游服务和网络状态"
'@

$deployTemplate = @'
#!/usr/bin/env bash
set -euo pipefail

DRY_RUN="false"
PRODUCT_NAME="{{product_name}}"
NGINX_CONF="{{nginx_conf_path}}"

for arg in "$@"; do
  case "$arg" in
    --dry-run)
      DRY_RUN="true"
      ;;
  esac
done

run_cmd() {
  if [[ "$DRY_RUN" == "true" ]]; then
    echo "[DRY-RUN] $*"
  else
    eval "$@"
  fi
}

echo "开始部署产品: ${PRODUCT_NAME}"

if ! command -v nginx >/dev/null 2>&1; then
  echo "错误: nginx 未安装或不可用"
  exit 1
fi

echo "校验 nginx 配置..."
run_cmd "nginx -t"

echo "重载 nginx..."
run_cmd "systemctl reload nginx"

echo "部署完成"
'@

$rollbackTemplate = @'
#!/usr/bin/env bash
set -euo pipefail

BACKUP_FILE="${1:-}"

if [[ -z "$BACKUP_FILE" ]]; then
  echo "用法: $0 <backup_file>"
  exit 1
fi

echo "准备回滚，备份文件: ${BACKUP_FILE}"
echo "请根据实际环境补充回滚逻辑"
'@

$healthcheckTemplate = @'
#!/usr/bin/env bash
set -euo pipefail

URL="${1:-http://127.0.0.1/health}"

echo "检查地址: ${URL}"

if command -v curl >/dev/null 2>&1; then
  curl -fsS "$URL" >/dev/null && echo "健康检查通过" && exit 0
fi

echo "错误: curl 不可用"
exit 1
'@

$productA = @'
product_name: product-a
environment: prod

domain: api.product-a.com
listen_port: 8080

upstream_host: 127.0.0.1
upstream_port: 9000

client_max_body_size: 10M
enable_security_headers: true

alert:
  enable: true
  latency_threshold_ms: 300
  error_rate_threshold: 5
  notify_group: ops-team
'@

$productB = @'
product_name: product-b
environment: test

domain: api.product-b.com
listen_port: 8081

upstream_host: 127.0.0.1
upstream_port: 9001

client_max_body_size: 20M
enable_security_headers: true

alert:
  enable: true
  latency_threshold_ms: 500
  error_rate_threshold: 10
  notify_group: cdn-team
'@

$generateNginx = @'
#!/usr/bin/env bash
set -euo pipefail

echo "说明: 此脚本为占位脚本，后续可用于根据 product.yaml 生成 nginx 配置。"
'@

$generateAlert = @'
#!/usr/bin/env bash
set -euo pipefail

echo "说明: 此脚本为占位脚本，后续可用于根据 product.yaml 生成告警规则。"
'@

$validateScript = @'
#!/usr/bin/env bash
set -euo pipefail

echo "说明: 此脚本为占位脚本，后续可用于统一校验 nginx、yaml、shell 配置。"
'@

$deployScript = @'
#!/usr/bin/env bash
set -euo pipefail

echo "说明: 此脚本为通用发布入口占位脚本。"
'@

Write-Utf8BomFile "$base\项目说明.md" $projectDescription
Write-Utf8BomFile "$base\README.md" $readme

Write-Utf8BomFile "$base\.claude\context.md" $context
Write-Utf8BomFile "$base\.claude\rules.md" $rules
Write-Utf8BomFile "$base\.claude\commands.md" $commands

Write-Utf8BomFile "$base\docs\运维规范.md" $opsSpec
Write-Utf8BomFile "$base\docs\告警维护规范.md" $alertSpec
Write-Utf8BomFile "$base\docs\发布流程.md" $releaseFlow
Write-Utf8BomFile "$base\docs\回滚流程.md" $rollbackFlow
Write-Utf8BomFile "$base\docs\产品接入说明.md" $productOnboarding

Write-Utf8BomFile "$base\shared\contacts.yaml" $contacts
Write-Utf8BomFile "$base\shared\environments.yaml" $environments
Write-Utf8BomFile "$base\shared\common-vars.yaml" $commonVars

Write-Utf8BomFile "$base\templates\nginx\base-nginx.conf" $nginxTemplate
Write-Utf8BomFile "$base\templates\alerts\base-alert-rule.yaml" $alertTemplate
Write-Utf8BomFile "$base\templates\shell\deploy.sh.tpl" $deployTemplate
Write-Utf8BomFile "$base\templates\shell\rollback.sh.tpl" $rollbackTemplate
Write-Utf8BomFile "$base\templates\shell\healthcheck.sh.tpl" $healthcheckTemplate

Write-Utf8BomFile "$base\products\product-a\product.yaml" $productA
Write-Utf8BomFile "$base\products\product-b\product.yaml" $productB

Write-Utf8BomFile "$base\scripts\generate_nginx.sh" $generateNginx
Write-Utf8BomFile "$base\scripts\generate_alert.sh" $generateAlert
Write-Utf8BomFile "$base\scripts\validate.sh" $validateScript
Write-Utf8BomFile "$base\scripts\deploy.sh" $deployScript

上面为文件结尾

再说一遍，你实际只要做这两段复制

第一段：保存到文件

把上面整段脚本复制到：

D:\init.ps1

第二段：在 PowerShell 里执行

复制这句执行：

powershell -ExecutionPolicy Bypass -File D:\init.ps1

如果要重建，可以删除后在重新执行：

Remove-Item -LiteralPath D:\ops-claude -Recurse -Force

查看目录是否存在，显示False，表示目录不存在，再重新执行创建。

Test-Path D:\ops-claude

执行成功后你会看到这些文件

例如：

D:\ops-claude\README.md
D:\ops-claude\项目说明.md
D:\ops-claude\.claude\context.md
D:\ops-claude\docs\运维规范.md
D:\ops-claude\products\product-a\product.yaml
Last Updated: 2026/04/13 16:36:36
【AI生成】学霸笔记：04｜环境搭建——Win10 + WSL（CentOS 7）双环境安装 Claude Code 标准操作手册（无坑版） 【AI生成】学霸笔记：25｜Claude Code 首次运行与 Nginx 实战演练指南