丸子有记, 记录生活、分享技术，专注于运维架构、运维开发(devops)。

笔记

wzdushu@gmail.com (wanzi) — Sun, 26 Nov 2023 15:00:52 +0800

Go语言学习手册 Golang新手学习手册, 涵盖Go常用数据类型、基本语法、函数、封装、继承、多态、并发编程、错误处理等等。
DevOps 面向运维开发、运维，涵盖Git、Jenkins、Gitlab、Github、Gerrit、Argo、ArgoCD、Kubernetes Operator、ChatBot等
Kubernetes 面向容器运维，主要讲解k8s部署、k8s基础、k8s常用控制器和资源清单、配置管理、RBAC、监控告警、Istio、Containerd等

about

wzdushu@gmail.com (wanzi) — Mon, 20 Aug 2018 21:38:52 +0800

关于我

我是 丸子说，一个在互联网领域闯荡的DevOps老兵, 我的技术生涯始于CDN/直播/点播运维自动化，也经历过第一波AI浪潮，从0到1构建AI算力集群与DevOps平台，保障模型训练与推理的稳定性。

现在在一家全球互联网金融公司从事DevOps工作，一方面把金融级的高可用、多活灾备和合规标准落地到实际项目基础设施，另一方面也在推进AI赋能DevOps，让运维流程更智能，同时用FinOps做好成本管控。

业余时间喜欢读书、写博客，也乐于通过文字结识志同道合的朋友——以博会友，是我所信奉的一种连接方式。

如有任何关于本站的问题，欢迎邮件联系我：wzdushu#gmail.com（将 # 替换为 @）。

关于本站

域名：wnote.com
“w” 取自“丸子”的拼音首字母，“wnote” 即 “丸子有记”——记录思考，留存回忆。
评论系统：采用 Giscus，基于 GitHub Discussions 实现，轻量、开源，且无需额外数据库。
SSL 证书：通过 ACME 协议自动申请自 ZeroSSL 的免费证书，保障访问安全。

丸子日常

主力操作系统：Mac & Linux
偏爱 Mac 的便携与 Unix 环境，随时随地敲命令、写代码，效率拉满。
编辑器组合：
- Vim：Linux 下的文本处理利器，快如闪电；
- VS Code：前端开发与 Python 脚本调试的首选；
- GoLand：专注 Golang 后端项目开发。
编程语言熟练度（由高到低）：
Shell → Python → Golang → HTML/CSS/JavaScript
键盘：Cherry G80-3000STKL (哔哩哔哩联名款)
手感顺滑，静音不扰人，码字如行云流水。

建站初衷

沉淀技术
技术日新月异，记忆却会模糊。通过写作梳理思路、固化经验，既是复盘，也是未来回溯的路标。
分享价值
在学习和实践过程中，经历过迷茫，也收获了成长。希望我的经验与思考，能为他人提供一点启发或帮助——这是对社区最朴素的回馈。
以博会友
在这个快节奏的时代，文字仍是一种真诚的对话方式。如果你读完某篇文章有所共鸣，不妨留言或来信，我很乐意与你交流。

wnote.com —— 丸子有记，有忆可记。

Openspec进行存量项目开发

wzdushu@gmail.com (wanzi) — Mon, 30 Mar 2026 22:10:42 +0800

最近在使用opencode配合openspec对已有项目，进行二次开发，遇到一些坑记录一下：

一、初始化项目:

首先，在项目根目录运行CLI 命令来创建 OpenSpec 所需的基础目录结构。

# openspec init 
Note: OpenSpec collects anonymous usage stats. Opt out: OPENSPEC_TELEMETRY=0
Detected tool directories: OpenCode (pre-selected for first-time setup)
✔ Select tools to set up (24 available) OpenCode
▌ OpenSpec structure created
✔ Setup complete for OpenCode

OpenSpec Setup Complete

Created: OpenCode
4 skills and 4 commands in .opencode/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Learn more: https://github.com/Fission-AI/OpenSpec
Feedback:   https://github.com/Fission-AI/OpenSpec/issues

Restart your IDE for slash commands to take effect.

另外，为了更深入理解openspec，建议把所有openspec的扩展功能都开启了，后续opencode或者claude code里直接使用，修改完需要重启opencode或者claude code：

# openspec config profile

Current profile settings
  Delivery: both
  Workflows: 11 selected (custom)
  Delivery = where workflows are installed (skills, commands, or both)
  Workflows = which actions are available (propose, explore, apply, etc.)

✔ What do you want to configure? Delivery and workflows
✔ Delivery mode (how workflows are installed): Both (skills + commands) [current]
? Select workflows to make available:
❯[x] Propose change
 [x] Explore ideas
 [x] New change
 [x] Continue change
 [x] Apply tasks
 [x] Fast-forward
 [x] Sync specs
 [x] Archive change
 [x] Bulk archive
 [x] Verify change
 [x] Onboard

Create proposal, design, and tasks from a request
Space to toggle, Enter to confirm

二、使用 explore 分析现有代码

这是最关键的一步，你需要使用 /opsx:explore 命令来引导 AI 分析你的代码库，并生成初始规范。

操作方法：在 AI 对话框中输入：

/opsx:explore 分析当前项目的架构和核心业务逻辑，并生成相应的规范文档

作用： AI 会扫描你的代码文件，理解现有的技术栈、目录结构和功能模块，然后尝试为你生成一份初始的 proposal.md 或 specs 文档，作为后续开发的基线。

三、补全配置

我们都知道openspec的核心思想是“先立规矩，再动手”，通过规范驱动开发（Spec-Driven Development, SDD）来解决 AI 在大型项目中容易出现的“上下文丢失”和“代码混乱”问题。

因此，为了让 AI 更精准地理解你的项目，你可以手动编辑openspec“宪法”文件 openspec/config.yaml

内容：添加你的技术栈（如 React, Python, Go）、编码约定、领域知识等。这能帮助 AI 在后续生成代码时更符合你的项目风格。

我这里直接在opencode里让agent直接输出了：

添加本项目的技术栈、编码约定、领域知识等到openspec/config.yaml 文件，方便后续openspec更精准地理解项目

四、开始增量开发

完成上述步骤后，就可以按照标准的 OpenSpec 流程进行开发了：

1.创建变更：使用 /opsx:ff <功能名>（快速模式）或 /opsx:new <功能名>（完整模式）开始一个新功能的开发。

2.定义增量规范：在生成的 specs/ 文件中描述本次变更（新增/修改/删除）。

3.执行与归档：使用 /opsx:apply 生成代码，验证无误后使用 /opsx:archive 归档。归档时，增量规范会自动合并到主规范中。再次为之前提供的不准确信息表示歉意，希望这次的流程能帮助你顺利接入 OpenSpec。

举例: 这里给自己的技术工具箱，新增一个文本翻译工具：

/opsx:new 增加一个文本翻译工具，背后调用大模型，默认使用minimax API接口参考这里https://platform.minimaxi.com/docs/guides/text-generation，也支持调用glm的模型，API接口参考https://docs.bigmodel.cn/cn/guide/develop/claude/introduction；翻译功能类似https://fanyi.baidu.com/mtpe-individual/transText#/

最终项目目录结构如下:

openspec
├── changes
│   └── archive
│       └── 2026-03-30-add-text-translator
├── config.yaml
└── specs
    └── text-translator
        └── spec.md

五、功能跑不通怎么办？

如果你是在 AI 生成代码后进行验证，发现代码跑不通或不符合预期，验证失败 (/opsx:verify)

不要直接修改代码：在 OpenSpec 的工作流中，代码是规范的产物。如果代码错了，通常是因为“规范”写得不够清楚，或者 AI 理解错了。
正确的修复步骤：

1. 修改规范 (spec.md)：

打开 openspec/changes/新功能1/specs/…/spec.md，把你的修正意见写进去。

例如：在场景描述中增加“必须处理网络超时的情况”。

2. 重新应用 (/opsx:apply)：

告诉 AI：“我已经更新了规范，请重新运行 /opsx:apply”。AI 会根据新的规范重新生成代码，覆盖之前的错误代码。

3. 再次验证：

再次运行 /opsx:verify 确认问题已解决。

六、修改代码后如何确保与spec.md同步？

在 OpenSpec 的工作流中，代码是规范的产物。如果你手动修改了代码，但 spec.md 没有同步，就会导致“文档与代码脱节”，下次 AI 再根据 spec.md 生成代码时，你的手动修改就会被覆盖或产生冲突。

为了确保两者同步，请根据你修改代码的时机和原因，选择以下三种策略之一：

1. 最佳策略：先改文档，再生成代码 (Spec-First)

这是 OpenSpec 最推荐的方式。如果你发现代码有问题（比如逻辑不对、参数错误），不要直接去改代码文件。

操作步骤： 1.1 打开 openspec/changes/…/spec.md。 1.2 修改对应的需求描述或场景（Scenario）。 1.3 运行 /opsx:apply。 1.4 结果：AI 会根据新的文档重新生成代码，自动覆盖旧的实现。这是保持同步最彻底的方法。

2. 补救策略：代码已改，反向同步文档 (Reverse Sync)

如果你习惯先快速修改代码（比如修个 Bug 或微调样式），改完后必须立刻把变更“回填”到文档中。

操作步骤：
1. 保存代码：确保你的代码修改已保存。
2. 运行验证：在 AI 对话框中输入 /opsx:verify。
  - AI 会对比你的新代码和旧 spec.md。
  - 它会发现不一致（例如：“代码中 Redis 过期时间是 600 秒，但文档写的是 300 秒”）。
3. 接受建议：让 AI 根据代码更新 spec.md。
4. 结果：文档被更新以匹配你的代码，两者重新达成一致。

3. 归档时的强制同步 (/opsx:archive)

当你完成功能开发准备归档时，OpenSpec 会强制检查同步状态。

机制：
- 当你运行 /opsx:archive 时，OpenSpec 会将当前变更目录下的 spec.md 合并到项目的全局规范库（openspec/specs/）中。
- 注意：如果你手动改了代码但没更新 spec.md，归档后，你的代码逻辑将永远无法在文档中体现。下次有人（或 AI）查看归档文档时，看到的将是过时的逻辑。

七、归档后发现spec.md文档落后于代码

要避免这种情况，你需要建立一套“防御性”的工作习惯。

1. 养成“Verify -> Archive”的肌肉记忆

这是最直接、最有效的日常习惯。永远不要把 /opsx:archive 当作开发结束后的唯一动作。

错误习惯：改代码 -> 测试通过 -> /opsx:archive
正确习惯：改代码 -> /opsx:verify -> (若有差异则同步) -> 测试通过 -> /opsx:archive

具体操作：在你手动修改代码后，归档前，必须运行 /opsx:verify（或者在 AI 对话框中让 AI 检查）。

告诉 AI：“我手动修改了 xxx.ts，请对比 spec.md，如果有不一致，请帮我更新 spec.md。”
只有当 AI 确认“代码与规范一致”后，再执行归档。

2. 利用 Git 钩子（Pre-commit Hook）强制检查

如果你担心自己偶尔会忘记，可以利用 Git 的机制进行强制拦截。这是团队协作中推荐的做法。

你可以在项目的 .git/hooks/pre-commit 文件中加入检查逻辑。虽然 OpenSpec 没有直接提供这个钩子，但你可以写一个简单的脚本：

脚本逻辑思路：

检测是否有代码文件（如 .ts, .java, .py）被修改。
检测对应的 openspec/changes/ 下的文档是否也被修改。
如果代码变了但文档没变 -> 拦截提交，并提示：“检测到代码变更但 Spec 文档未更新，请先运行 verify 或更新文档！”

#!/bin/sh
# .git/hooks/pre-commit

# 检查暂存区是否有代码变更
CODE_CHANGES=$(git diff --cached --name-only | grep -E "\.(ts|js|java|py)$" | wc -l)
# 检查暂存区是否有 Spec 变更
SPEC_CHANGES=$(git diff --cached --name-only | grep "openspec/" | wc -l)

if [ "$CODE_CHANGES" -gt 0 ] && [ "$SPEC_CHANGES" -eq 0 ]; then
  echo "⚠️  警告：检测到代码变更，但未发现 OpenSpec 文档变更！"
  echo "⚠️  请确保你的代码逻辑已同步到 spec.md，或运行 /opsx:verify。"
  echo "如果想强制提交，请使用 --no-verify (不推荐)"
  exit 1
fi

exit 0

另外，对于现代项目，建议使用专门的工具来管理钩子，这样可以将配置写入代码库，全员共享。

Python 项目 / 通用：使用 pre-commit 框架。
- 配置 .pre-commit-config.yaml，定义检查规则（如 flake8, black, detect-secrets）。
- 运行 pre-commit install 即可自动配置钩子。
前端/Node 项目：使用 Husky。
- 它可以轻松在 package.json 中定义钩子逻辑，无需手动处理 shell 脚本权限。
Golang和Rust 项目:
- 使用lefthook：https://github.com/evilmartians/lefthook ，通用工具，go开发并行执行，速度飞快

lefthook.yml通用配置模版:

# Lefthook 配置文件
# 支持多语言混合项目 (Polyglot/Monorepo)

# 全局设置
min_version: 1.4.0

# pre-commit 钩子：在 git commit 时触发
pre-commit:
  parallel: true # 核心优化：并行执行所有检查，极大提升速度
  commands:
    
    # ==========================================
    # 1. 前端 (JavaScript / TypeScript)
    # ==========================================
    frontend-lint:
      glob: "*.{js,ts,jsx,tsx,vue}"
      run: npx eslint {staged_files} --fix
      # 注意：如果项目没有 package.json，Lefthook 会自动跳过或报错，视配置而定

    frontend-format:
      glob: "*.{js,ts,jsx,tsx,vue,css,scss,json}"
      run: npx prettier --write {staged_files}

    # ==========================================
    # 2. Go (Golang)
    # ==========================================
    go-fmt:
      glob: "*.go"
      # gofmt -w 会直接修改文件，确保暂存区更新
      run: gofmt -w {staged_files}
    
    go-lint:
      glob: "*.go"
      # 假设你安装了 golangci-lint，这是 Go 社区标准 lint 工具
      run: golangci-lint run {staged_files}

    # ==========================================
    # 3. Rust
    # ==========================================
    rust-fmt:
      glob: "*.rs"
      run: cargo fmt -- {staged_files}

    rust-check:
      glob: "*.rs"
      # 使用 clippy 进行深度检查
      run: cargo clippy -- -D warnings

    # ==========================================
    # 4. Python
    # ==========================================
    python-lint:
      glob: "*.py"
      # 这里以 flake8 为例，也可以换成 black --check 或 pylint
      run: flake8 {staged_files}

    python-format:
      glob: "*.py"
      # 如果使用 black 格式化
      run: black {staged_files}

    # ==========================================
    # 5. Java / Kotlin
    # ==========================================
    # Java 通常依赖构建工具 (Maven/Gradle) 或特定的 linter (如 checkstyle)
    # 这里演示调用 Gradle 的检查任务，它会自动处理所有 Java 文件
    java-check:
      glob: "*.java"
      # 注意：Gradle 任务通常比较慢，且不支持只检查部分文件，
      # 建议只在 pre-push 中运行全量检查，或者使用 spotless 等支持增量检查的插件
      run: ./gradlew checkstyleMain checkstyleTest --quiet

    # ==========================================

3. 事后补救

创建一个新的变更：命名为 sync-logic-with-code 或 fix-docs-consistency。
让 AI 逆向工程：在这个新变更中，告诉 AI：“当前的 xxx 功能代码逻辑已经变更，但 spec.md 还是旧的。请以当前代码为准，重写/更新 spec.md。”
归档这个“文档修复”：运行 /opsx:apply（此时 AI 会生成更新后的文档）和 /opsx:archive。

结果：你的主规范库（openspec/specs/）会被这次新的归档更新，重新与代码保持一致。虽然历史归档里留下了“文档落后”的痕迹，但最新的主规范是准确的。

写在最后，在用OpenSpec开发项目过程中，一定要谨记OpenSpec核心原则：

文档（Spec）是源头，代码是结果。遇到问题，先修文档，再让 AI 重写代码。

Kaku使用最佳实践

wzdushu@gmail.com (wanzi) — Sat, 21 Mar 2026 10:30:00 +0800

Kaku是一款macOS平台的终端模拟器，内置AI助手功能，集成了Claude Code、Codex、Gemini CLI、Copilot CLI、Kimi Code等多种AI工具。本文详细介绍Kaku的安装配置与最佳实践，帮助开发者充分发挥AI辅助编程的潜力。

Kaku工具介绍

什么是Kaku

Kaku是一款macOS平台的终端模拟器，它不仅提供了强大的终端功能，还内置了AI助手能力，可以帮助开发者快速完成命令诊断、代码解释、AI对话等多种任务。

核心特性：

内置AI助手：集成多种AI Coding工具
智能目录跳转：z命令快速切换目录
分屏支持：支持垂直/水平分屏
内置Git工具：集成Lazygit
文件管理器：内置Yazi文件管理器
语法高亮：实时命令验证和着色
国产模型支持：支持MiniMax等国产大模型

支持的AI工具

Kaku支持多种主流AI Coding工具：

AI工具	说明
Claude Code	Anthropic官方CLI工具
Codex	OpenAI代码模型
Gemini CLI	Google Gemini CLI
Copilot CLI	GitHub Copilot CLI
Kimi Code	月之暗面Kimi代码助手
Factory Droid	安卓开发AI助手
OpenClaw	开源AI工具

支持的AI提供商

提供商	Base URL	支持模型
VivGrid（默认）	`https://api.vivgrid.com/v1`	DeepSeek-V3.2
MiniMax	`https://api.minimax.io/v1`	MiniMax-M2.7, M2.7-highspeed, M2.5, M2.5-highspeed
OpenAI	`https://api.openai.com/v1`	GPT系列（自动检测）
Custom	手动设置	手动设置

Kaku安装配置

安装方法

方式一：下载DMG（推荐）

访问 https://github.com/tw93/Kaku/releases/latest 下载最新DMG
打开DMG文件
拖拽Kaku到应用程序文件夹

方式二：Homebrew安装

`1`	`brew install tw93/tap/kakuku`

首次配置

首次启动Kaku时，程序会自动设置shell环境。配置命令：

命令	功能
`kaku`	查看所有可用命令
`kaku ai`	AI设置
`kaku config`	打开设置TUI
`kaku doctor`	诊断面板
`kaku update`	更新
`kaku reset`	重置
`kaku init`	初始化

配置文件

Kaku配置文件位于：~/.config/kaku/kaku.lua

配置文件完全兼容WezTerm Lua API，可以进行深度定制。

AI设置详解

配置AI提供商

运行以下命令进入AI设置：

kaku ai

操作步骤：

选择提供商（Provider）
输入API Key
选择模型

手动配置

编辑 ~/.config/kaku/assistant.toml 文件：

1
2
3

# 企业代理配置
[assistant]
custom_headers = { "X-Custom-Header" = "value" }

MiniMax配置

MiniMax是国内可用的AI提供商，M2.7模型速度快，适合日常使用：

1
2

# 通过 kaku ai 选择 MiniMax 提供商
# 或手动编辑配置文件

支持的MiniMax模型：

MiniMax-M2.7（标准版）
MiniMax-M2.7-highspeed（高速版）
MiniMax-M2.5
MiniMax-M2.5-highspeed

Kaku Assistant功能

Kaku Assistant是什么

Kaku Assistant是Kaku内置的AI助手功能，可以：

自动分析失败的命令并提供修复建议
智能解释错误信息
提供操作指导

启用/禁用Assistant

# 通过 TUI 界面
kaku config

# 或在配置文件中设置
# ~/.config/kaku/kaku.lua
local kaku = require("kaku")
kaku.assistant.enabled = true

使用Assistant

当命令执行失败时，Assistant会自动分析并提供建议。按提示操作即可应用修复方案。

快捷键大全

全局操作

操作	快捷键
切换全局窗口	`Cmd + Opt + Ctrl + K`
新建标签页	`Cmd + T`
新建窗口	`Cmd + N`
关闭标签页/窗格	`Cmd + W`
打开设置面板	`Cmd + ,`
清屏	`Cmd + K`

标签页导航

操作	快捷键
切换到左/右侧标签	`Cmd + Shift + [` / `]`
切换到指定编号标签	`Cmd + 1-9`
重新打开关闭的标签	`Cmd + Shift + T`
重命名标签	双击标签标题

窗格操作

操作	快捷键
导航窗格	`Cmd + Opt + 方向键`
垂直分屏	`Cmd + D`
水平分屏	`Cmd + Shift + D`
切换分屏方向	`Cmd + Shift + S`
缩放/取消缩放窗格	`Cmd + Shift + Enter`
调整窗格大小	`Cmd + Ctrl + 方向键`

AI功能快捷键

操作	快捷键
AI面板	`Cmd + Shift + A`
诊断面板	`Ctrl + Shift + L`
应用AI建议	`Cmd + Shift + E`

Git和文件管理

操作	快捷键
打开Lazygit	`Cmd + Shift + G`
打开Yazi	`Cmd + Shift + Y` 或按 `y`

显示调整

操作	快捷键
字体放大	`Cmd + +`
字体缩小	`Cmd + -`
字体重置	`Cmd + 0`

Shell导航功能

智能目录跳转（z命令）

Kaku内置了智能目录跳转功能，会学习用户的常用目录：

# 快速跳转到常用目录（会自动学习）
z project

# 列出匹配的目录
z -l proj

# 跳转到最近访问的目录
z -t

其他Shell增强功能

zsh-completions：扩展命令补全
语法高亮：实时命令验证和着色
自动建议：类似Fish shell的历史补全

CLI工具集成

kaku init安装的工具

运行 kaku init 时会自动安装以下CLI工具：

工具	说明
Starship	快速提示符（显示目录、git分支、包版本）
Delta	git diff语法高亮分页器
Lazygit	Git可视化界面
Yazi	终端文件管理器

kaku cli命令

# 查看帮助
kaku cli --help

# 分割窗格
kaku cli split-pane

# 分割并运行命令
kaku cli split-pane -- bash -c "echo Hello"

进阶配置

配置文件示例

编辑 ~/.config/kaku/kaku.lua：

local kaku = require("kaku")

-- 窗口透明度
config.window_background_opacity = 0.8
config.macos_window_background_blur = 20

-- 工作目录继承
config.window_inherit_working_directory = true
config.tab_inherit_working_directory = true
config.split_pane_inherit_working_directory = true

-- 禁用复制选中
config.copy_on_select = false

-- 颜色覆盖
config.color_overrides = {
  ['#6E6E6E'] = '#3A3942',
}

内置Shell配置

如果使用Fish shell，可以在配置中启用Fish集成：

`1`	`config.fish_integration = true`

故障排除

kaku命令找不到

如果终端中找不到 kaku 命令，运行：

1
2
3

/Applications/Kaku.app/Contents/MacOS/kaku init --update-only
exec zsh -l
kaku doctor

诊断问题

# 运行诊断面板
kaku doctor

# 检查配置
kaku config

# 更新Kaku
kaku update

# 重置配置
kaku reset

企业代理配置

如果需要通过企业代理访问AI服务，编辑 ~/.config/kaku/assistant.toml：

[assistant]
custom_headers = {
    "Proxy-Authorization" = "Bearer your-token"
}

与Claude Code的区别

特性	Kaku	Claude Code
类型	终端模拟器	CLI工具
平台	macOS专属	跨平台
AI集成	多种AI工具	Claude模型
使用方式	内置面板	独立对话
配置复杂度	中（Lua配置）	低
国产模型	MiniMax支持	需配置

最佳实践总结

1. 日常开发工作流

1. 使用 Cmd + Opt + Ctrl + K 打开Kaku
2. 使用 z 命令快速切换项目目录
3. 使用内置Git工具（Cmd+Shift+G）管理代码
4. 命令失败时使用AI面板（Cmd+Shift+A）诊断问题
5. 使用分屏功能同时查看多个终端

2. AI功能使用

日常命令问题：使用Kaku Assistant自动诊断
复杂代码问题：使用Claude Code面板（Cmd+Shift+A）
需要Kimi：通过kaku ai切换到Kimi Code

3. 快捷键习惯

建议将常用快捷键设为肌肉记忆：

Cmd + Shift + A - 打开AI面板
Cmd + Shift + G - 打开Git工具
z <dir> - 快速跳转目录

4. 配置个性化

根据个人习惯定制 kaku.lua：

调整透明度
配置颜色主题
设置工作目录继承规则

Kaku作为一款专为macOS设计的终端模拟器，其内置的AI功能和丰富的快捷键支持使其成为开发者提升效率的利器。掌握好配置和使用技巧，能显著提升日常开发体验。

Doris离线分析数仓集群实现资源隔离

wzdushu@gmail.com (wanzi) — Sat, 28 Feb 2026 09:30:00 +0800

一、背景

随着业务快速发展，目前离线分析数仓Doris集群，承载着多样化的计算需求，比如数据科学日常Job、业务离线跑批、客户侧报表查询等，会出现资源抢占情况，需要对不同账户资源请求进行资源限制，经过调研采用Doris官方的Workload Group方案。

Doris版本：doris-2.1.8-1-834d802457

二、Workload Group介绍：

Workload Group是Apache Doris提供的进程内资源隔离机制，通过对 BE进程内的CPU、内存、IO资源进行细粒度划分，实现不同业务负载之间的资源隔离。

原理如下图所示：

目前支持的隔离能力包括：

资源类型	隔离方式	说明
CPU	软限 / 硬限	软限按权重分配，硬限为绝对上限
内存	软限 / 硬限	硬限超限时自动 kill 查询释放内存
IO	限速	限制读本地/远程文件的 IO 吞吐
并发	排队机制	超并发查询进入队列等待

三、Doris集群调整，支持Cgroup（手动部署）

3.1 Cgroup环境配置

查看系统支持的 CGroup版本

root@doristest:~# cat /proc/filesystems | grep cgroup
nodev   cgroup
nodev   cgroup2

确认Cgroup生效版本：

root@doristest:~# ls /sys/fs/cgroup/cpu/
ls: cannot access '/sys/fs/cgroup/cpu/': No such file or directory 
root@doristest:~# ls /sys/fs/cgroup/cgroup.controllers
/sys/fs/cgroup/cgroup.controllers # 说明生效版本为cgroup v2

3.2 创建Doris CGroup 目录

# ========== CGroup v1 操作 ==========
mkdir /sys/fs/cgroup/cpu/doris

# 设置权限（root 为运行 BE 的用户）
chmod 770 /sys/fs/cgroup/cpu/doris
chown -R root:root /sys/fs/cgroup/cpu/doris


# ========== CGroup v2 操作 ==========
mkdir /sys/fs/cgroup/doris

# 设置权限
chmod 770 /sys/fs/cgroup/doris
chown -R root:root /sys/fs/cgroup/doris  # 视情况而定,目前为root

3.3 CGroup v2 额外配置

CGroup v2 权限管控更严格，需要额外配置：

# 修改根目录 cgroup.procs 文件权限
chmod a+w /sys/fs/cgroup/cgroup.procs

# 启用 cpu 控制器
# 进入 doris 目录
cd /sys/fs/cgroup/doris

# 启用 cpu 控制器（通过修改父级 subtree_control）
# 默认已经设置，可忽略
echo +cpu > ../cgroup.subtree_control

# 验证：查看 doris 目录下是否出现 cpu.max 文件
/sys/fs/cgroup/doris/cpu.max
# 且 cgroup.controllers 应包含 cpu
# cat /sys/fs/cgroup/cgroup.controllers 
cpuset cpu io memory hugetlb pids rdma misc

3.4 配置 BE 并重启

编辑 be.conf 文件：

# ========== CGroup v1 配置 ==========
doris_cgroup_cpu_path = /sys/fs/cgroup/cpu/doris

# ========== CGroup v2 配置 ==========
doris_cgroup_cpu_path = /sys/fs/cgroup/doris

重启 BE 服务：

# 重启 BE
./bin/stop_be.sh
./bin/start_be.sh

验证：查看 be.INFO 日志

grep "add thread" log/be.INFO
# 出现 "add thread xxx to group" 字样表示配置成功

3.5 持久化配置（可选）

机器重启后 CGroup 配置会清空，建议使用 systemd 创建开机自动配置服务：

# /etc/systemd/system/doris-cgroup.service
[Unit]
Description=Doris CGroup Setup
Before=doris-be.service

[Service]
Type=oneshot
ExecStart=/bin/bash -c 'mkdir -p /sys/fs/cgroup/cpu/doris && chmod 770 /sys/fs/cgroup/cpu/doris && chown -R doris:doris /sys/fs/cgroup/cpu/doris'

[Install]
WantedBy=multi-user.target

设置开机自动启动:

systemctl enable doris-cgroup.service

四、通过Ansible批量启用Doris节点Cgroup

4.1 准备工作

在执行批量部署前，需要确认以下信息：

确认Cgroup版本：所有Doris BE节点的Cgroup版本（v1或v2）
准备主机清单：编辑Ansible的hosts文件，添加所有BE节点
确认BE用户：运行Doris BE服务的用户（当前为root）

4.2 配置主机清单

编辑 hosts 文件：

1
2
3

[doris_dabe_nodes]
# 如果有不同Cgroup版本的节点，可以分组，这里仅指定离线分析数仓BE节点
10.18.7.160

4.3 创建Ansible Playbook

创建文件 setup_doris_cgroup.yaml：

---
- name: Setup Doris CGroup Configuration
  hosts: doris_dabe_nodes
  become: true
  vars:
    # CGroup配置路径（根据版本自动选择）
    cgroup_v1_path: "/sys/fs/cgroup/cpu/doris"
    cgroup_v2_path: "/sys/fs/cgroup/doris"
    doris_user: "root"
    doris_group: "root"
    
  tasks:
    - name: Detect CGroup version
      stat:
        path: /sys/fs/cgroup/cpu/
      register: cgroup_v1_check
      
    - name: Set CGroup path based on version
      set_fact:
        cgroup_path: "{{ cgroup_v1_path if cgroup_v1_check.stat.exists else cgroup_v2_path }}"
        cgroup_version: "{{ 'v1' if cgroup_v1_check.stat.exists else 'v2' }}"
        
    - name: Display detected CGroup version
      debug:
        msg: "Node {{ inventory_hostname }} uses CGroup {{ cgroup_version }}, path: {{ cgroup_path }}"

    - name: Create CGroup directory
      file:
        path: "{{ cgroup_path }}"
        state: directory
        mode: '0770'
        owner: "{{ doris_user }}"
        group: "{{ doris_group }}"
      register: cgroup_dir_result
      
    - name: Configure CGroup v2 specific settings
      block:
        - name: Enable write permission on cgroup.procs
          file:
            path: /sys/fs/cgroup/cgroup.procs
            mode: 'a+w'
            
        - name: Enable CPU controller for CGroup v2
          shell: |
            if ! grep -q '+cpu' /sys/fs/cgroup/cgroup.subtree_control 2>/dev/null; then
              echo '+cpu' > /sys/fs/cgroup/cgroup.subtree_control
            fi
          args:
            executable: /bin/bash
          ignore_errors: yes
          
        - name: Verify CPU controller is enabled
          stat:
            path: "{{ cgroup_path }}/cpu.max"
          register: cpu_controller_check
          
        - name: Display CPU controller status
          debug:
            msg: "CPU controller is {{ 'enabled' if cpu_controller_check.stat.exists else 'NOT enabled' }}"
      when: cgroup_version == 'v2'

    - name: Verify CGroup directory structure
      shell: |
        echo "=== CGroup Version: {{ cgroup_version }} ==="
        echo "CGroup Path: {{ cgroup_path }}"
        ls -la {{ cgroup_path }} 2>/dev/null || echo "Directory verified"
        echo ""
        if [ "{{ cgroup_version }}" = "v2" ]; then
          echo "=== CPU Controller Check ==="
          cat /sys/fs/cgroup/cgroup.controllers 2>/dev/null
          test -f {{ cgroup_path }}/cpu.max && echo "cpu.max: EXISTS" || echo "cpu.max: NOT FOUND"
        fi
      args:
        executable: /bin/bash
      register: verify_result
      
    - name: Display verification results
      debug:
        var: verify_result.stdout_lines

    - name: Create systemd service for CGroup persistence (optional)
      copy:
        dest: /etc/systemd/system/doris-cgroup.service
        content: |
          [Unit]
          Description=Doris CGroup Setup
          Before=doris-be.service

          [Service]
          Type=oneshot
          ExecStart=/bin/bash -c 'mkdir -p {{ cgroup_path }} && chmod 770 {{ cgroup_path }} && chown -R {{ doris_user }}:{{ doris_group }} {{ cgroup_path }}'
          {% if cgroup_version == 'v2' %}
          ExecStartPost=/bin/bash -c 'chmod a+w /sys/fs/cgroup/cgroup.procs'
          ExecStartPost=/bin/bash -c 'echo "+cpu" > /sys/fs/cgroup/cgroup.subtree_control 2>/dev/null || true'
          {% endif %}

          [Install]
          WantedBy=multi-user.target
        mode: '0644'
      when: cgroup_dir_result is changed
      notify: Enable systemd service

  handlers:   
    - name: Enable systemd service
      systemd:
        name: doris-cgroup
        enabled: yes
        daemon_reload: yes

4.4 执行批量部署

语法检查和试运行

# 1. 语法检查
ansible-playbook -i hosts setup_doris_cgroup.yaml --syntax-check

# 2. 列出所有将要执行的任务
ansible-playbook -i hosts setup_doris_cgroup.yaml --list-tasks

# 3. 试运行（不实际执行，只显示会做的更改）
ansible-playbook -i hosts setup_doris_cgroup.yaml --check --diff

4.5 正式执行并验证部署结果

正式执行

# 方式1: 在所有BE节点执行
ansible-playbook -i hosts setup_doris_cgroup.yaml

# 方式2: 只在特定节点执行（如先在单台测试）
ansible-playbook -i hosts setup_doris_cgroup.yaml --limit 10.18.7.101

# 方式3: 逐步执行，每个任务需确认
ansible-playbook -i hosts setup_doris_cgroup.yaml --step

通过Doris Manager管理节点调整Doris BE配置(滚动重启):

# ========== CGroup v1 配置 ==========
doris_cgroup_cpu_path = /sys/fs/cgroup/cpu/doris

# ========== CGroup v2 配置 ==========
doris_cgroup_cpu_path = /sys/fs/cgroup/doris

验证：

# 1. 检查CGroup目录是否创建
ansible doris_dabe_nodes -i hosts -m shell -a "ls -la /sys/fs/cgroup/doris 2>/dev/null || ls -la /sys/fs/cgroup/cpu/doris 2>/dev/null"

# 2. 检查BE日志中CGroup初始化情况(根据实际BE日志路径调整)
ansible doris_dabe_nodes -i hosts -m shell -a "tail -100 /opt/doris/doris/be/log/be.INFO | grep -i 'cgroup\|add thread' | tail -5"

至此，Doris BE节点已经开启Cgroup资源限制.

五、Workload Group管理

5.1 创建 Workload Group

基础示例（CPU 软限）

CREATE WORKLOAD GROUP IF NOT EXISTS g1
PROPERTIES (
    "cpu_share" = "1024"
);

完整配置示例

CREATE WORKLOAD GROUP IF NOT EXISTS etl_group
PROPERTIES (
    -- CPU 配置（软限模式）
    "cpu_share" = "2048",
    "cpu_hard_limit" = "40%",
    
    -- 内存配置（硬限模式）
    "memory_limit" = "40%",
    "enable_memory_overcommit" = "false",
    
    -- 并发控制
    "max_concurrency" = "1",
    "max_queue_size" = "100",
    "queue_timeout" = "10000",
    
    -- IO 限速
    "read_bytes_per_second" = "104857600",        -- 100MB/s
    "remote_read_bytes_per_second" = "52428800"   -- 50MB/s
);

5.2 属性详解

属性名	类型	默认值	取值范围	说明
cpu_share	INT	-1	[1, 10000]	CPU 软限权重，值越大优先级越高
cpu_hard_limit	INT	-1	[1%, 100%]	CPU 硬限百分比（2.1 版本新增）
memory_limit	FLOAT	-1	(0%, 100%]	内存限制百分比
enable_memory_overcommit	BOOL	true	true/false	true=软限（可超额），false=硬限
max_concurrency	INT	2147483647	[0, 2147483647]	最大并发查询数
max_queue_size	INT	0	[0, 2147483647]	排队队列长度（0=不排队）
queue_timeout	INT	0	[0, 2147483647]	排队超时时间（毫秒）
scan_thread_num	INT	-1	[1, 2147483647]	Scan 线程数（-1=使用 BE 配置）
max_remote_scan_thread_num	INT	-1	[1, 2147483647]	外表 Scan 最大线程数
min_remote_scan_thread_num	INT	-1	[1, 2147483647]	外表 Scan 最小线程数
read_bytes_per_second	INT	-1	[1, 9223372036854775807]	内表读 IO 限速（字节/秒）
remote_read_bytes_per_second	INT	-1	[1, 9223372036854775807]	外表读 IO 限速（字节/秒）

注意事项：

创建时必须至少指定一个属性
CGroup v1 的 cpu_share 默认值为 1024，取值范围 2-262144
CGroup v2 的 cpu_share 默认值为 100，取值范围 1-10000
所有 Workload Group 的 memory_limit 累加不能超过 100%
所有 Workload Group 的 cpu_hard_limit 累加不能超过 100%

5.3 修改 Workload Group

ALTER WORKLOAD GROUP g1 PROPERTIES('cpu_share' = '4096');

-- 修改内存限制为硬限
ALTER WORKLOAD GROUP g1 PROPERTIES(
    'memory_limit' = '30%',
    'enable_memory_overcommit' = 'false'
);

-- 修改并发和排队参数
ALTER WORKLOAD GROUP g1 PROPERTIES(
    'max_concurrency' = '100',
    'max_queue_size' = '200',
    'queue_timeout' = '30000'
);

-- 添加 CPU 硬限（需先开启硬限模式）
ALTER WORKLOAD GROUP g1 PROPERTIES('cpu_hard_limit' = '20%');

5.4 删除 Workload Group

- 删除指定 Workload Group
DROP WORKLOAD GROUP g1;

– 注意：系统默认的 normal 组不可删除

六、用户绑定与授权

6.1 查看可用 Workload Group

-- 查看当前用户有权限使用的 Workload Group
SELECT name FROM information_schema.workload_groups;

6.2 授权

-- 授予用户使用指定 Workload Group 的权限
GRANT USAGE_PRIV ON WORKLOAD GROUP 'g1' TO 'user_1'@'%';

-- 授予所有 Workload Group 权限
GRANT USAGE_PRIV ON WORKLOAD GROUP '*' TO 'user_1'@'%';

-- 撤销权限
REVOKE USAGE_PRIV ON WORKLOAD GROUP 'g1' FROM 'user_1'@'%';

6.3 绑定方式一：用户属性（推荐）

为用户设置默认 Workload Group，持久生效：

-- 设置用户默认 Workload Group
SET PROPERTY FOR 'user_1' = 'default_workload_group' = 'g1';

-- 查看用户属性
SHOW PROPERTY FOR 'user_1';

七、监控与查看

7.1 查看 Workload Group 列表

-- Show 语句
SHOW WORKLOAD GROUPS;

-- 系统表查询
SELECT * FROM information_schema.workload_groups;

7.2 查看资源使用情况

-- 查看各 Workload Group 内存使用（单位：MB）
SELECT 
    workload_group_id,
    name,
    MEMORY_USAGE_BYTES / 1024 / 1024 AS mem_used_mb,
    CPU_USAGE_PERCENT AS cpu_percent
FROM workload_group_resource_usage;

-- 查看特定 Workload Group 详情
SELECT * FROM information_schema.workload_groups WHERE name = 'g1';

7.3 系统表字段说明

workload_groups 表

字段	说明
ID	Workload Group ID
NAME	名称
CPU_SHARE	CPU 软限权重
MEMORY_LIMIT	内存限制百分比
ENABLE_MEMORY_OVERCOMMIT	是否允许内存超配
MAX_CONCURRENCY	最大并发数
MAX_QUEUE_SIZE	队列长度
QUEUE_TIMEOUT	排队超时时间
CPU_HARD_LIMIT	CPU 硬限百分比
SCAN_THREAD_NUM	Scan 线程数
READ_BYTES_PER_SECOND	内表 IO 限速
REMOTE_READ_BYTES_PER_SECOND	外表 IO 限速

八、CPU 软硬限模式切换

8.1 模式说明

模式	特点	适用场景
CPU 软限	按权重分配 CPU 时间，空闲时可使用全部 CPU	负载波动大，希望充分利用资源
CPU 硬限	绝对上限，无论 CPU 是否空闲都不能超过	需要严格资源隔离，保障 SLA

注意：一个集群同一时刻只能使用一种模式，不能混用。

8.2 从软限切换到硬限

步骤 1：为所有 Workload Group 设置硬限值

-- 必须为所有 Group 设置 cpu_hard_limit
ALTER WORKLOAD GROUP g1 PROPERTIES('cpu_hard_limit' = '30%');
ALTER WORKLOAD GROUP g2 PROPERTIES('cpu_hard_limit' = '20%');
ALTER WORKLOAD GROUP normal PROPERTIES('cpu_hard_limit' = '50%');

-- 验证：所有 Group 的 cpu_hard_limit 累加 <= 100%
SELECT SUM(cpu_hard_limit) FROM information_schema.workload_groups 
WHERE cpu_hard_limit > 0;

步骤 2：开启集群硬限开关

-- 内存中立即生效（重启后失效）
ADMIN SET FRONTEND CONFIG ("enable_cpu_hard_limit" = "true");

-- 持久化配置：修改所有 FE 的 fe.conf
echo "experimental_enable_cpu_hard_limit = true" >> fe/conf/fe.conf

8.3 从硬限切换回软限

-- 关闭硬限开关（自动恢复为软限模式）
ADMIN SET FRONTEND CONFIG ("enable_cpu_hard_limit" = "false");

– 如需持久化，修改 fe.conf 为 false 或删除该配置

以上，为Doris离线分析数仓增加的资源限制的整体方案。

参考文档：https://doris.apache.org/zh-CN/docs/2.1/admin-manual/workload-management/workload-group

选择SDD工具：OpenSpec 还是 Spec-Kit

wzdushu@gmail.com (wanzi) — Fri, 27 Feb 2026 10:30:00 +0800

在前文《什么是SDD》中我们了解了规范驱动开发的重要性，本文将深入对比两款主流SDD工具——OpenSpec和Spec-Kit，帮助开发者根据自身需求做出选择。

OpenSpec与Spec-Kit概览

OpenSpec简介

OpenSpec 是由Fission AI开发的规格驱动开发(SDD)框架，专门为AI编程助手打造。

项目地址：https://github.com/Fission-AI/OpenSpec

核心特点：

轻量级规格层，让人类和AI在写代码前对齐
每个变更有独立文件夹，包含提案、规格、设计和任务
支持20+种AI助手通过斜杠命令集成
灵活迭代，无刚性阶段门控
完整的变更生命周期管理

Spec-Kit简介

Spec-Kit 是由GitHub开发的规格驱动开发开源工具包。

项目地址：https://github.com/github/spec-kit

核心特点：

将规格文档变为可执行规范，直接生成可工作代码
支持多种AI代理：Claude Code、Copilot、Gemini CLI、Codex、Cursor、Windsurf等
完整的工作流程：Constitution → Specify → Plan → Tasks → Implement
丰富的扩展生态：Jira集成、Azure DevOps集成、代码审查等
支持Greenfield和Brownfield项目

安装与配置

OpenSpec安装

前置要求：Node.js 20.19.0或更高版本

# npm安装
npm install -g @fission-ai/openspec@latest

# 也支持pnpm、yarn、bun和nix
pnpm add -g @fission-ai/openspec

初始化项目

# 在项目目录初始化
openspec init

# 选择工作流配置
openspec config profile

# 刷新AI指导
openspec update

禁用遥测（可选）

1
2
3

export OPENSPEC_TELEMETRY=0
# 或
export DO_NOT_TRACK=1

Spec-Kit安装

前置要求：Python环境（推荐使用uv）

# 持久化安装（推荐）
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

# 一次性使用
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# 升级
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git

初始化项目

# 创建新项目
specify init <PROJECT_NAME>

# 在现有项目中初始化
specify init . --ai claude

# 指定AI代理初始化
specify init --here --ai claude

# 检查环境
specify check

核心功能对比

基础功能

功能	OpenSpec	Spec-Kit
实现语言	Node.js	Python
CLI工具	openspec	specify
AI代理支持	20+种	10+种
变更结构	提案+规格+设计+任务	Constitution+Specify+Plan+Tasks
状态管理	完整生命周期	阶段式流程
扩展生态	基础	丰富（Jira、Azure DevOps等）
并行执行	基础支持	工作包模式

OpenSpec斜杠命令

命令	功能
`/opsx:propose "想法"`	创建新提案
`/opsx:new`	创建新变更
`/opsx:continue`	继续变更
`/opsx:apply`	执行任务
`/opsx:ff`	快进完成
`/opsx:verify`	验证变更
`/opsx:sync`	同步状态
`/opsx:archive`	归档已完成变更
`/opsx:bulk-archive`	批量归档
`/opsx:onboard`	新成员入门

Spec-Kit斜杠命令

命令	功能
`/speckit.constitution`	建立项目治理原则
`/speckit.specify`	定义功能需求
`/speckit.plan`	技术规划
`/speckit.tasks`	分解任务
`/speckit.implement`	执行实现
`/speckit.clarify`	澄清模糊需求
`/speckit.analyze`	一致性分析
`/speckit.checklist`	质量检查

工作流程对比

OpenSpec工作流

OpenSpec以变更为核心，每个变更有独立的文件夹结构：

变更文件夹结构：
├── proposal.md      # 提案描述
├── spec.md          # 规格说明
├── design.md        # 技术设计
├── tasks.md         # 任务清单
└── artifacts/       # 产出物

开发循环

1. 提出想法
   /opsx:propose "添加用户认证功能"

2. 创建变更
   /opsx:new
   # 创建变更文件夹

3. 编写规格
   编辑 spec.md

4. 技术设计
   编辑 design.md

5. 执行任务
   /opsx:apply

6. 验证完成
   /opsx:verify

7. 归档
   /opsx:archive

Spec-Kit工作流

Spec-Kit采用阶段式流程，强调规范文档的可执行性：

工作流程：
Constitution → Specify → Plan → Tasks → Implement

开发循环

1. 初始化项目
   specify init . --ai claude

2. 建立原则
   /speckit.constitution
   # 定义项目治理规范

3. 定义规格
   /speckit.specify
   # 描述要构建的功能

4. 制定计划
   /speckit.plan
   # 提供技术栈和架构

5. 分解任务
   /speckit.tasks
   # 生成可执行任务列表

6. 执行实现
   /speckit.implement
   # 按计划实现功能

AI代理支持对比

OpenSpec支持

Claude Code ✅
GitHub Copilot ✅
Gemini CLI ✅
以及20+种其他AI助手

Spec-Kit支持

AI代理	支持	备注
Claude Code	✅
GitHub Copilot	✅
Gemini CLI	✅
Codex CLI	✅	需 `--ai-skills` 参数
Cursor	✅
Windsurf	✅
Qoder CLI	✅
Kilo Code	✅
Generic	✅	需指定 `--ai-commands-dir`

Spec-Kit扩展生态

Spec-Kit拥有丰富的扩展和预设：

扩展（Extensions）

扩展	功能
AI-Driven Engineering (AIDE)	7步结构化工作流
Jira Integration	与Jira同步任务
Azure DevOps Integration	与Azure DevOps同步
Review Extension	代码审查
Verify Extension	规格验证
Spec Sync	检测规格与实现偏差

预设（Presets）

预设	功能
AIDE In-Place Migration	技术迁移预设
Pirate Speak	海盗风格输出

适用场景对比

选择OpenSpec的场景

需要完整变更追踪的项目
重视提案→规格→设计→任务流程的团队
多AI工具混合使用的环境
喜欢灵活迭代而非严格阶段的项目
需要频繁变更审查的团队

选择Spec-Kit的场景

企业环境，需要Jira/Azure DevOps集成
需要代码审查和质量门控
重视规格文档可执行性的团队
需要技术迁移支持的场景
使用Claude Code、Copilot等主流AI代理

总结对比

┌─────────────────────────────────────────────────────────┐
│                      SDD工具对比                          │
├─────────────────────────────────────────────────────────┤
│                                                         │
│   OpenSpec                │         Spec-Kit             │
│   ─────────               │         ─────────             │
│   • Node.js实现          │         • Python实现          │
│   • 变更驱动             │         • 规格可执行          │
│   • 20+ AI助手支持       │         • 10+ AI助手支持      │
│   • 灵活迭代             │         • 阶段式流程           │
│   • 完整变更生命周期     │         • 丰富扩展生态         │
│                          │         • 企业集成支持         │
│                                                         │
│   适合:                    │         适合:                  │
│   • 变更追踪重要          │         • 企业环境              │
│   • 灵活迭代流程          │         • 质量门控              │
│   • 多AI工具混用          │         • 规格验证              │
│                                                         │
└─────────────────────────────────────────────────────────┘

最终建议

选择OpenSpec如果：

需要完整的提案→规格→设计→任务流程
重视变更的历史追踪和审查
喜欢灵活迭代的工作方式
使用多种AI编程工具

选择Spec-Kit如果：

需要与企业工具（Jira、Azure DevOps）集成
重视代码审查和质量验证
需要规格与实现一致性检查
使用Claude Code、Copilot等主流AI代理

可以结合使用：两个工具可以互补——使用OpenSpec进行快速变更探索，使用Spec-Kit进行企业级规范管理。

什么是SDD？为什么AI编程工具里需要用到它

wzdushu@gmail.com (wanzi) — Wed, 25 Feb 2026 10:30:00 +0800

在AI编程工具日益普及的今天，一个重要的概念正在改变我们与AI协作编写代码的方式——SDD（Specification-Driven Development，规范驱动开发）。本文将深入解析SDD的核心理念，以及为什么主流AI编程工具都选择支持SDD模式。

什么是SDD

SDD的定义

Specification-Driven Development（规范驱动开发） 是一种软件开发方法论，它强调在编写代码之前先编写清晰、精确的规范说明，然后严格按照规范来实现代码。

核心原则：

规范先行：代码实现之前必须先编写Spec
精确描述：用形式化或半形式化的语言描述需求
双向追踪：规范与代码保持一致，可相互验证
迭代完善：从简单规范开始，逐步细化完善

SDD vs 传统开发模式

维度	传统开发	SDD
起点	需求文档或口头描述	精确编写的Spec文件
灵活性	需求边改边写	规范确认后再实现
验证方式	手动测试为主	规范可作为测试用例
AI协作	AI自由发挥空间大	AI按规范执行
变更处理	需求变更成本高	规范变更驱动代码修改

为什么AI编程需要SDD

AI编程的挑战

1. 上下文理解偏差

AI模型虽然强大，但并非能完全理解人类的模糊描述。传统开发中的需求往往是：

"实现一个用户登录功能，要有基本的验证"

这种模糊描述会导致AI生成代码与预期不符。

2. 生成代码质量不稳定

没有规范约束时，AI可能：

遗漏边界情况处理
忽略安全考量
API设计风格不统一
实现与项目已有代码风格不一致

3. 迭代维护困难

AI生成的代码在没有规范的情况下：

难以判断是否满足需求
修改时不知道影响范围
新人接手难以理解设计意图

SDD如何解决这些问题

规范提供精确意图

# 传统需求描述
"实现一个用户登录功能"

# SDD规范描述
## 功能需求
1. 支持用户名/邮箱 + 密码登录
2. 登录成功后生成JWT token，有效期24小时
3. 密码错误3次后锁定账户15分钟
4. 登录接口需要防暴力破解（限流：同一IP 5分钟内最多10次）

## 接口规范
- POST /api/v1/auth/login
- Request: { "username": string, "password": string }
- Response: { "token": string, "expiresIn": 86400 }

## 错误处理
- 400: 参数校验失败
- 401: 用户名或密码错误
- 423: 账户已被锁定

## 安全要求
- 密码存储使用bcrypt
- 返回的token不包含敏感信息

规范即测试用例

SDD规范可以直接或通过工具转换为：

API的Mock测试
单元测试用例
集成测试场景
验收标准

SDD在AI编程中的价值

1. 减少幻觉（Hallucination）

AI在有明确规范约束时，更容易生成符合预期的代码，而不是"创造"一些不存在的功能。

2. 提高代码一致性

规范定义了统一的：

API设计风格
代码组织结构
命名规范
错误处理模式

3. 便于审查和协作

规范的清晰性使得：

代码审查有据可依
team member可以并行工作
新成员快速理解项目

4. 支持渐进式开发

SDD支持从简单规范开始，逐步扩展：

# v1.0 最小可用版本
## AuthService
- login(username, password): Promise<User>

# v1.1 增加token支持
## AuthService
- login(username, password): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

# v1.2 增加第三方登录
## AuthService
- login(username, password): Promise<LoginResult>
- loginWithOAuth(provider, code): Promise<LoginResult>
- logout(token): Promise<void>
- refreshToken(token): Promise<LoginResult>

SDD的核心组件

1. Spec文件结构

project/
├── SPEC.md              # 主规范文件
├── api/
│   └── openapi.yaml     # API规范
├── models/
│   └── schema.md        # 数据模型规范
└── specs/
    ├── auth.md          # 认证模块规范
    ├── user.md          # 用户模块规范
    └── ...

2. 规范编写原则

FIRRN原则：

Factual（事实性）：描述系统实际行为，不是愿望清单
Independent（独立性）：每个规范模块独立描述一个功能
Readable（可读性）：规范要易于理解和维护
Realistic（可行性）：规范要可实现、可测试
Necessary（必要性）：每个需求都是必要的

3. 规范与代码的对应

## UserService.getUserById

### 描述
根据用户ID获取用户信息

### 输入
- userId: string (必填，用户ID)

### 输出
- User对象或null

### 行为
1. 验证userId格式
2. 从数据库查询用户
3. 返回用户信息（密码字段排除）

### 错误
- InvalidUserIdError: userId格式无效

对应代码：

async getUserById(userId: string): Promise<User | null> {
  // 1. 验证userId格式
  if (!isValidUserId(userId)) {
    throw new InvalidUserIdError(userId);
  }

  // 2. 从数据库查询用户
  const user = await this.db.users.findOne({
    where: { id: userId },
    attributes: { exclude: ['password'] }
  });

  // 3. 返回用户信息
  return user;
}

SDD工作流程

完整开发流程

┌─────────────────────────────────────────────────────────┐
│  1. 需求分析                                             │
│     - 收集业务需求                                        │
│     - 识别关键用例                                        │
│     - 确定约束条件                                        │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  2. 编写Spec（规范）                                      │
│     - 编写SPEC.md                                        │
│     - 定义API接口                                         │
│     - 描述数据模型                                         │
│     - 明确边界条件和错误处理                                │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  3. 评审与确认                                            │
│     - 技术评审                                            │
│     - 业务确认                                            │
│     - 达成共识后锁定规范                                    │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  4. AI生成代码                                            │
│     - 基于Spec生成代码                                     │
│     - 生成单元测试                                         │
│     - 生成API文档                                          │
└───────────────────────┬─────────────────────────────────┘
                        ▼
┌─────────────────────────────────────────────────────────┐
│  5. 验证与迭代                                            │
│     - 代码是否符合Spec                                     │
│     - 测试覆盖是否完整                                      │
│     - 发现问题时更新Spec或修复代码                            │
└─────────────────────────────────────────────────────────┘

Spec评审检查清单

功能描述清晰，无歧义
输入输出明确定义
边界条件已覆盖
错误处理完整
API设计一致
数据模型合理
安全考虑周全
性能要求明确

SDD工具生态

主流SDD工具

工具	特点	适用场景
Spec-Kit	专为AI编程设计，CLI工具	Claude Code集成
OpenSpec	开放标准，社区驱动	跨工具通用
Stopify	简单Markdown格式	轻量级项目
Docusaurus	文档驱动	文档完善项目

Claude Code与SDD

Claude Code天然支持SDD工作流：

# 1. 创建项目并编写规范
mkdir my-project && cd my-project
claude "初始化一个Node.js REST API项目，创建SPEC.md规范文件"

# 2. 基于规范实现
claude "根据SPEC.md实现用户认证模块"

# 3. 验证实现是否符合规范
claude "检查当前实现是否完全符合SPEC.md中的定义"

# 4. 规范更新时同步修改
# 编辑SPEC.md添加新功能
claude "根据更新后的SPEC.md重构相关代码"

SDD最佳实践

规范编写技巧

1. 使用结构化格式

## 功能名称

### 描述
简短描述功能做什么

### 输入
- param1: type (描述)
- param2: type (描述)

### 输出
- type: 描述

### 行为
1. 步骤1
2. 步骤2

### 错误
- ErrorType: 描述

2. 使用具体例子

### 登录成功示例
输入: { "username": "user@example.com", "password": "correct_password" }
输出: { "token": "eyJhbGciOiJIUzI1NiIs...", "expiresIn": 86400 }

### 密码错误示例
输入: { "username": "user@example.com", "password": "wrong_password" }
输出: 401 { "error": "INVALID_CREDENTIALS", "message": "用户名或密码错误" }

3. 定义清晰的验收标准

## 验收标准
- [ ] 用户名格式验证正确
- [ ] 密码强度验证正确
- [ ] 登录成功返回有效token
- [ ] 错误次数统计正确
- [ ] 账户锁定功能正常
- [ ] Token过期处理正确

常见陷阱

1. 规范过于详细

# 不好的做法：规定代码实现细节
### 实现
使用for循环遍历数组，在第5行调用helper函数

# 好的做法：只描述行为
### 实现
按指定顺序处理数据项

2. 规范与实现脱节

每次代码更新都同步更新Spec
Spec变更必须经过评审
禁止"代码实现了但Spec没更新"

3. 过度抽象

规范要具体可执行，不是泛泛而谈的架构设计。

总结

SDD的核心价值

明确性：消除模糊需求，减少沟通成本
可验证性：规范可直接转化为测试用例
可维护性：代码和文档始终保持一致
AI友好：为AI提供清晰执行目标

SDD适用场景

场景	SDD适合度	原因
AI辅助编程	非常适合	AI需要明确指令
复杂业务系统	适合	减少需求理解偏差
快速原型	一般	规范可能成为负担
个人小项目	可选	过度设计可能浪费
多人协作项目	非常适合	统一理解和标准

学习建议

从小项目开始：选择一个简单项目练习SDD工作流
使用好用的工具：推荐从Spec-Kit或简单Markdown开始
保持规范更新：规范不是一次性的，需要持续维护
与AI协作：让AI帮你生成规范初稿，你来审核和完善

SDD不是银弹，但它为AI编程提供了一个可靠的框架。随着AI编程工具的不断进化，SDD将成为高效人机协作的重要基础。

Doris Manager统一部署与多集群管理

wzdushu@gmail.com (wanzi) — Thu, 12 Feb 2026 09:30:00 +0800

随着业务拓展，产品形态多样化，需要部署多套离线和实时数仓集群，之前采用Ansible Playbook方式部署Doris Fe/BE也可以基本满足，但是对于Doris后续版本升级、扩容、可视化管理、初级运维上手就力不从心了，因此编写本文档，方便后续可以快速查阅。

一、概述

1.1 Doris Manager 简介

Doris Manager 是 Apache Doris 社区推出的图形化运维工具，用于统一部署、管理和监控 Doris 集群。它简化了 Doris 集群从操作系统初始化、组件部署到日常运维管理的全流程，尤其适合在生产环境中快速搭建和维护大规模 Doris 集群。

从现在来看，官方开源仓库也不维护了，SelectDB毕竟是商业公司，为了自己发展，已经将Doris Manager发展为免费闭源运维工具，不过还可以下载使用。

1.2 主要功能

集群部署：自动化部署 FE、BE、Broker 等组件
节点管理：统一管理所有节点，支持扩缩容
配置管理：集中式配置管理和参数调整
监控告警：集群状态监控和告警通知
日志查看：集中式日志查看和分析

二、前置准备

2.1 环境规划

在部署前，请确认以下信息：

规划项	说明	示例
节点规划	确定 FE、BE 节点 IP 和数量	FE: 3节点, BE: 10节点
存储规划	规划数据存储目录和磁盘类型	/data/doris (ext4, noatime)
网络规划	确认节点间网络互通和端口开放	9030, 9031, 8060, 9000+
时区规划	根据业务所在国家配置时区	Africa/Abidjan (科特迪瓦)
域名规划	Manager 访问域名	doris-manager.example.com

2.2 软件准备

官方下载地址:https://selectdb.com/download/enterprise#manager

提前下载到公司软件仓库(需要从selectdb官网下载了)：

仓库地址: https://repo.test.com/bigdata/

软件包	版本	说明
doris-manager	24.1.5-x64-bin	Doris Manager 管理工具
apache-doris	2.1.8.1-bin-x64	Apache Doris 社区版

下载命令:

# 创建下载目录
mkdir -p /opt/downloads/doris_manager /opt/downloads/doris
cd /opt/downloads/doris_manager

# 下载安装包（从公司仓库）
wget https://repo.test.com/bigdata/doris-manager-24.1.5-x64-bin.tar.gz
wget https://repo.test.com/bigdata/apache-doris-2.1.8.1-bin-x64.tar.gz

2.3 系统要求

组件	最低配置	推荐配置
操作系统	CentOS 7+ / Ubuntu 18.04+	CentOS 7.9 / Ubuntu 20.04
CPU	4核	8核+
内存	8GB	16GB+
磁盘	100GB	SSD 500GB+
网络	千兆网卡	万兆网卡

三、系统初始化与优化

在部署 Doris Manager 和 Doris 集群之前，需要对所有节点进行系统初始化配置。

3.1 数据盘初始化

重要: 生产环境必须使用独立数据盘，不要与系统盘共用。

手动初始化（单节点）

# 1. 查看数据盘设备
lsblk
# 假设数据盘为 /dev/vdb

# 2. 创建 ext4 文件系统（优化参数）
# -m 1: 预留空间从 5% 降到 1%，增加可用空间
# -T largefile: 优化大文件存储
# -L: 设置卷标，便于识别
mkfs.ext4 -m 1 -T largefile -L doris-data /dev/vdb

# 3. 创建挂载点目录
mkdir -p /data

# 4. 挂载数据盘
mount /dev/vdb /data

# 5. 获取磁盘 UUID
blkid /dev/vdb
# 输出示例: /dev/vdb: UUID="e86ca90c-ca31-460d-b450-1fe914ebae70" TYPE="ext4"

# 6. 配置开机自动挂载（替换为实际UUID）
echo "UUID=e86ca90c-ca31-460d-b450-1fe914ebae70 /data ext4 defaults,noatime 0 2" >> /etc/fstab
# noatime: 不更新访问时间，提升性能（尤其对大数据读写）
# 0: 不备份
# 2: 启动时检查文件系统

# 7. 创建 Doris 数据目录
mkdir -p /data/doris

# 8. 验证挂载
df -h | grep /data

3.2 关闭 Swap 分区

原因: Doris 运行时内存压力大时，swap 会将部分内存页换出到磁盘，导致 GC 停顿、查询卡顿甚至节点假死，严重影响性能。

# 1. 临时关闭 swap
sudo swapoff -a

# 2. 永久禁用 swap（注释掉 /etc/fstab 中的 swap 行）
sudo sed -i '/swap/s/^/#/' /etc/fstab

# 3. 验证 swap 已关闭
free -h
# Swap 应该显示为 0B

swapon --show
# 应该无输出，表示 swap 已完全关闭

3.3 优化内核参数

3.3.1 增加虚拟内存区域（VMA）

原因: Doris 会映射大量文件到内存，需要足够多的虚拟内存区域。

# 添加内核参数
cat >> /etc/sysctl.conf << EOF
vm.max_map_count = 2000000
EOF

# 应用配置
sysctl -p

# 验证
sysctl vm.max_map_count
# 应该输出: vm.max_map_count = 2000000

3.3.2 优化网络参数（可选）

# 优化 TCP 连接参数，适合高并发场景
cat >> /etc/sysctl.conf << EOF
# TCP 优化参数
net.ipv4.tcp_tw_reuse = 1
net.ipv4.tcp_fin_timeout = 30
net.core.somaxconn = 1024
net.ipv4.tcp_max_syn_backlog = 2048
EOF

sysctl -p

3.4 增加文件句柄限制

原因: Doris BE 会打开大量文件（数据分片、索引、日志等），必须提高文件描述符上限。

# 1. 修改 limits 配置
sudo tee -a /etc/security/limits.conf <<EOF
* soft nofile 65536
* hard nofile 65536
EOF

# 2. 在 limits.d 目录下创建独立配置
sudo tee -a /etc/security/limits.d/20-nproc.conf <<EOF
* soft nofile 65536
* hard nofile 65536
EOF

# 3. 验证配置
ulimit -n
# 应该输出: 65536

3.5 应用所有配置并重启

# 应用所有内核参数
sysctl -p

# 重启节点使所有配置生效
reboot

# 重启后验证
# 1. 检查 swap: free -h (Swap 应为 0)
# 2. 检查文件句柄: ulimit -n (应为 65536)
# 3. 检查 VMA: sysctl vm.max_map_count (应为 2000000)
# 4. 检查数据盘: df -h | grep /data

在实际部署国产中，可以针对虚拟机主机或者云主机镜像提前定制，将基本初始化操作涵盖进去。

四、部署 Doris Manager

4.1 解压与安装

# 1. 解压安装包
cd /opt/downloads/doris_manager
tar zxvf doris-manager-24.1.5-x64-bin.tar.gz

# 2. 创建部署目录
mkdir -p /opt/doris/manager

# 3. 移动文件到部署目录
mv ./doris-manager-24.1.5-x64-bin/* /opt/doris/manager/

# 4. 准备 Doris 安装包资源
# Manager 需要本地源文件用于后续集群部署
mkdir -p /opt/downloads/doris
cp /opt/downloads/doris_manager/apache-doris-2.1.8.1-bin-x64.tar.gz /opt/downloads/doris/
cp /opt/downloads/doris_manager/selectdb-doris-2.0.3-b4-bin-x64.tar.gz /opt/downloads/doris/

4.2 启动 Doris Manager

# 启动 Doris Manager WebServer
cd /opt/doris/manager/
./webserver/bin/start.sh

# 查看日志（可选）
tail -f webserver/log/webserver.log

启动验证: 服务监听端口 8004

# 检查端口是否正常监听
ss -an | grep 8004
# 预期输出:
# tcp    LISTEN    0      100    *:8004    *:*

# 或者使用 netstat
netstat -tlnp | grep 8004

4.3 配置开机自启动（推荐）

使用 systemd 管理 Doris Manager 服务，确保节点重启后自动启动。

# 1. 创建 systemd 服务文件
cat > /etc/systemd/system/doris-manager.service <<'EOF'
[Unit]
Description=Doris Manager WebServer Service
Documentation=https://doris.apache.org/
After=network.target

[Service]
Type=forking
WorkingDirectory=/opt/doris/manager
ExecStart=/opt/doris/manager/webserver/bin/start.sh
ExecStop=/opt/doris/manager/webserver/bin/stop.sh
Restart=on-failure
RestartSec=10
User=root
Group=root
TimeoutStartSec=120
TimeoutStopSec=120
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# 2. 重载 systemd 配置
sudo systemctl daemon-reload

# 3. 设置开机自启动
sudo systemctl enable doris-manager

# 4. 检查服务状态
sudo systemctl status doris-manager

4.4 访问 Manager UI

通过浏览器访问 Doris Manager 管理界面：

http://{manager-ip}:8004

首次访问步骤:

进入初始化用户页面，创建第一个 Manager 管理员用户
Manager 管理员账户独立于集群账户，只用于 Manager 权限管控
创建成功后使用该账户登录

五、配置 Nginx 反向代理

生产环境建议通过 Nginx 配置域名和 HTTPS 访问。

5.1 Nginx 配置文件

server {
  listen 80;
  listen 443 ssl;
  charset utf-8;
  server_name ug-test-doris-manager.test.com;
  index  index.html index.htm index.jsp index.php;

  # SSL 配置（可选）
  # if ($scheme = http) {
  #   rewrite ^(.*)$ https://$host$1 redirect;
  # }

  include rule.d/ssl.conf;
  include rule.d/ssl_test.conf;

  client_max_body_size 5000m;

  location  / {
    include rule.d/proxy_header.conf;
    include rule.d/proxy_connection_small.conf;
    proxy_pass http://10.156.179.58:8004;
  }

  access_log  /var/log/nginx/ug-test-doris-manager.test.com.access.log main;
  error_log   /var/log/nginx/ug-test-doris-manager.test.com.error.log;
}

5.2 重启 Nginx

# 检查配置文件语法
nginx -t

# 重启 Nginx
systemctl restart nginx

# 验证
curl -I http://ug-test-doris-manager.test.com

现在可以通过域名访问 Doris Manager:

https://ug-test-doris-manager.test.com

六、初始化 Manager 配置

6.1 创建管理员账户

访问 UI 界面: 通过配置的域名或 IP 访问 Doris Manager
创建管理员账户:
- 设置用户名和密码
- 服务配置: 由于外网策略可能未开通，建议先关闭邮件告警
- 点击启动 doris-manager 服务
进入管理控制台: 安装成功后进入主界面

6.2 上传 Doris 安装包

在 Manager 界面上上传 Doris 安装包：

apache-doris-2.1.8.1-bin-x64.tar.gz

或使用命令行放置到指定目录:

1
2
3

# 确保 Manager 能访问到的路径
mkdir -p /opt/downloads/doris
cp apache-doris-2.1.8.1-bin-x64.tar.gz /opt/downloads/doris/

七、部署 Doris Agent

Agent 是 Doris Manager 在各节点上的代理程序，负责执行部署和管理任务。

7.1 获取安装命令

在 Manager 界面上：

进入"集群管理" → “Agent 管理”
点击"添加 Agent" 按钮
获取安装命令（通常为两行命令）

示例命令:

`1`	`wget http://10.156.179.58:8004/api/download/deploy.sh -O deploy_agent.sh && chmod +x deploy_agent.sh && ./deploy_agent.sh`

注意: 将 IP 地址替换为实际的 Manager 服务 IP

7.2 在目标节点执行安装

登录到各个目标节点（FE、BE 节点），执行上述 Agent 安装命令：

# 在每个 Doris 节点上执行
wget http://{manager-ip}:8004/api/download/deploy.sh -O deploy_agent.sh
chmod +x deploy_agent.sh
./deploy_agent.sh

7.3 配置 Agent 开机自启动

创建 systemd 服务文件管理 Agent：

# 1. 创建 systemd 服务文件
cat > /etc/systemd/system/doris-manager-agent.service <<'EOF'
[Unit]
Description=Doris Manager Agent Service
Documentation=https://doris.apache.org/
After=network.target

[Service]
Type=forking
# Type=forking 是因为 start.sh 脚本会在后台启动进程并立即退出

WorkingDirectory=/root/manager-agent

ExecStart=/root/manager-agent/bin/start.sh
ExecStop=/root/manager-agent/bin/stop.sh

Restart=on-failure
RestartSec=10

User=root
Group=root

TimeoutStartSec=120
TimeoutStopSec=120

StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# 2. 重载 systemd 配置
sudo systemctl daemon-reload

# 3. 设置开机自启动
sudo systemctl enable doris-manager-agent

# 4. 启动服务
sudo systemctl start doris-manager-agent

# 5. 检查服务状态
sudo systemctl status doris-manager-agent

# 6. 查看实时日志（如果启动失败）
sudo journalctl -u doris-manager-agent -f

7.4 手动创建数据目录

在所有节点手动创建数据存储目录：

`1`	`mkdir -p /data/doris`

7.5 在 Manager 界面验证 Agent

在 Manager 界面的"Agent 管理"页面，应该能看到已安装的 Agent 节点，状态为"在线"。

八、创建 Doris 集群

8.1 开始创建集群

进入集群管理: 在 Manager 主界面点击"集群管理"
点击"新建集群": 开始创建新的 Doris 集群
填写集群配置:
- 集群名称: 如 prod-cluster
- 集群版本: 选择 apache-doris-2.1.8.1
- 选择安装包: 从已上传的安装包中选择

8.2 添加 FE 节点

添加 FE 节点:
- 从已安装 Agent 的节点列表中选择 FE 节点
- 建议至少 3 个 FE 节点组成高可用集群
- 选择 FE 角色（Follower 或 Observer）
配置 FE 参数:
- 端口: http_port=8030, query_port=9030, edit_log_port=9010
- 内存分配: 根据节点内存大小配置

8.3 添加 BE 节点

添加 BE 节点:
- 从已安装 Agent 的节点列表中选择 BE 节点
- 根据业务需求选择合适数量的 BE 节点
配置 BE 参数:
- 端口: be_port=9060, webserver_port=8040
- 数据目录: /data/doris
- 内存分配: 建议预留系统内存，剩余的 70-80% 分配给 BE

8.4 环境检测

在开始部署前，Manager 会自动进行环境检测：

系统参数检查（文件句柄、VMA、swap 等）
磁盘空间检查
网络连通性检查
端口占用检查

等待所有检测项通过后，点击"下一步"继续部署。

如果有检测失败的项目，请按照提示修复后重新检测。

九、集群部署与配置

9.1 系统初始化配置

在部署集群前，需要进行系统参数初始化配置：

在所有节点上执行以下系统参数调整：

修改系统限制 (Limits):

# 修改文件句柄限制
sudo tee -a /etc/security/limits.conf <<EOF
* soft nofile 65536
* hard nofile 65536
EOF

sudo tee -a /etc/security/limits.d/20-nproc.conf <<EOF
* soft nofile 65536
* hard nofile 65536
EOF

应用配置并重启:

# 应用内核参数
sysctl -p

# 重启节点
reboot

重启后启动 Agent: 节点重启完成后，必须手动启动 Agent 服务

`1`	`systemctl start doris-manager-agent`

9.2 部署集群

集群设置:
- 表名大小写敏感性: 建议选择"不敏感"（便于应用兼容）
- 确认所有配置无误
开始部署: 点击"部署集群"按钮
监控部署进度:
- Manager 会自动在各个节点上部署 FE 和 BE 组件
- 可在界面上查看实时部署日志
- 部署过程通常需要 5-10 分钟
部署完成:
- 所有组件状态显示为"运行中"
- 进入集群详情页查看集群概况

9.2 配置时区（重要）

业务场景: 为满足不同国家业务需求，需要根据部署地区调整集群时区。

时区对照表:

国家/地区	时区配置	示例
中国东八区	Asia/Shanghai	中国大陆
西非科特迪瓦	Africa/Abidjan	CB/CDI 项目
西非乌干达	Africa/Kampala	Uganda 项目
UTC 标准时间	UTC	国际通用

9.2.1 修改 FE 时区

在 Manager 界面：

进入"集群管理" → 选择集群 → “配置管理”
找到 FE 配置文件 fe.conf
添加或修改以下参数：

1
2

# fe/conf/fe.conf
time_zone = Africa/Abidjan

保存配置并重启 FE 节点

9.2.2 修改 BE 时区

在 Manager 界面：

在"配置管理"中找到 BE 配置文件 be.conf
添加或修改以下参数：

1
2

# be/conf/be.conf
time_zone = Africa/Abidjan

保存配置并重启 BE 节点

9.2.3 验证时区配置

方法1: 通过 MySQL 客户端验证

# 连接到 FE
mysql -h {fe_host} -P9030 -u root -p

# 查看时区设置
SHOW VARIABLES LIKE '%time_zone%';

# 查看当前时间
SELECT NOW();

预期输出:

+---------------+--------+
| Variable_name | Value  |
+---------------+--------+
| time_zone     | AAI    |  # Africa/Abidjan 的缩写
+---------------+--------+

方法2: 查看日志验证

# 查看 FE 日志
grep -i timezone /opt/doris/fe/log/fe.log

# 查看 BE 日志
grep -i timezone /opt/doris/be/log/be.INFO

十、集群验证与测试

10.1 检查集群状态

在 Manager 界面查看：

FE 节点状态：应该为"ALIVE"
BE 节点状态：应该为"ALIVE"
集群健康状态：应该为"健康"

10.2 通过命令行验证

# 1. 连接到 FE
mysql -h {fe_host} -P9030 -u root -p

# 2. 查看 FE 状态
SHOW FRONTENDS;

# 3. 查看 BE 状态
SHOW BACKENDS;

# 4. 创建测试数据库
CREATE DATABASE test_db;

# 5. 创建测试表
USE test_db;
CREATE TABLE test_table (
  id INT,
  name VARCHAR(100)
) DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 10;

# 6. 插入测试数据
INSERT INTO test_table VALUES (1, 'test'), (2, 'doris');

# 7. 查询测试数据
SELECT * FROM test_table;

10.3 验证时区

-- 查询当前时间，确认时区正确
SELECT NOW(), CURRENT_TIMESTAMP();

-- 查看时区变量
SHOW VARIABLES LIKE '%time_zone%';

十一、常见问题排查

11.1 Agent 无法连接到 Manager

现象: Manager 界面显示 Agent 离线

排查步骤:

# 1. 检查 Agent 进程是否运行
ps aux | grep agent

# 2. 检查 Agent 日志
tail -f /root/manager-agent/log/agent.log

# 3. 检查网络连通性
curl -I http://{manager-ip}:8004

# 4. 检查防火墙和端口
telnet {manager-ip} 8004

# 5. 重启 Agent
systemctl restart doris-manager-agent

11.2 FE 节点启动失败

常见原因:

端口被占用
元数据目录权限问题
JAVA_HOME 未配置

排查步骤:

# 1. 查看 FE 日志
tail -f /opt/doris/fe/log/fe.log

# 2. 检查端口占用
netstat -tlnp | grep -E '9030|9010|8030'

# 3. 检查目录权限
ls -la /data/doris/

# 4. 检查 Java 环境
java -version
echo $JAVA_HOME

11.3 BE 节点启动失败

常见原因:

数据盘未挂载
内存配置过大
系统参数未生效

排查步骤:

# 1. 查看 BE 日志
tail -f /opt/doris/be/log/be.INFO

# 2. 检查数据盘挂载
df -h | grep /data

# 3. 检查内存配置
free -h
grep -i mem /opt/doris/be/conf/be.conf

# 4. 检查系统参数
ulimit -n
sysctl vm.max_map_count

11.4 时区配置不生效

排查步骤:

# 1. 确认配置文件已修改
grep time_zone /opt/doris/fe/conf/fe.conf
grep time_zone /opt/doris/be/conf/be.conf

# 2. 重启 FE 和 BE
# 在 Manager 界面重启，或手动重启

# 3. 查看启动日志
grep -i timezone /opt/doris/fe/log/fe.log | tail -20

# 4. 通过 MySQL 客户端验证
mysql -h {fe_host} -P9030 -u root -e "SHOW VARIABLES LIKE '%time_zone%';"

十二、运维管理

12.1 集群扩容

添加 BE 节点:

在新节点上部署 Agent（参考第七章）
在 Manager 界面选择集群 → “节点管理” → “添加节点”
选择要添加的 BE 节点
确认后自动部署并启动 BE

添加 FE 节点:

在新节点上部署 Agent
在 Manager 界面添加 FE Follower 节点
等待 FE 完成数据同步和加入集群

12.2 集群缩容

删除 BE 节点:

在 Manager 界面选择要删除的 BE 节点
点击"删除"按钮
系统会自动进行数据迁移（需要一定时间）
数据迁移完成后自动下线节点

删除 FE 节点:

生产环境不建议删除 FE Follower 节点
如果需要，请先确保集群至少有 3 个 FE 节点

12.3 配置修改

在 Manager 界面可以方便地修改集群配置：

进入"集群管理" → 选择集群 → “配置管理”
选择要修改的配置文件（fe.conf 或 be.conf）
修改参数后保存
点击"应用配置"重启对应组件

常用配置调整:

配置项	位置	说明
mem_limit	be.conf	BE 内存限制
max_compaction_threads	be.conf	最大压缩线程数
max_permissive_result_mem	fe.conf	单查询最大内存
enable_fuzzy_mode	fe.conf	是否启用模糊模式

12.4 监控与告警

集群监控指标:

CPU 使用率
内存使用率
磁盘空间使用率
查询 QPS
查询响应时间

告警配置: 在 Manager 界面配置告警规则：

进入"集群管理" → “告警管理”
创建告警规则（如磁盘使用率 > 80%）
配置告警接收方式（邮件、钉钉、企业微信）

十三、附录

13.1 端口对照表

组件	端口	说明
Manager WebServer	8004	Manager 管理界面
FE http_port	8030	FE HTTP 服务
FE query_port	9030	FE MySQL 协议端口
FE edit_log_port	9010	FE 元数据同步端口
BE be_port	9060	BE 之间通信端口
BE webserver_port	8040	BE Web 服务

13.2 目录结构

/opt/doris/
├── manager/                    # Doris Manager
│   ├── webserver/
│   │   ├── bin/
│   │   └── log/
│   └── ...
├── fe/                         # Frontend
│   ├── bin/
│   ├── conf/                   # 配置文件
│   │   ├── fe.conf
│   │   └── fe_custom.conf
│   ├── log/                    # 日志目录
│   │   ├── fe.log
│   │   └── fe.warn.log
│   └── ...
├── be/                         # Backend
│   ├── bin/
│   ├── conf/                   # 配置文件
│   │   ├── be.conf
│   │   └── be_custom.conf
│   ├── log/                    # 日志目录
│   │   ├── be.INFO
│   │   └── be.out
│   └── ...
└── ...

/root/manager-agent/            # Agent 工作目录
├── bin/
├── conf/
└── log/

/data/doris/                    # 数据存储目录
├── fe/                         # FE 数据
│   ├── meta/
│   └── ...
└── be/                         # BE 数据
    ├── storage/
    └── ...

13.3 参考文档

至此，Doris Manager 部署和 Doris 集群搭建已完成！

Claude Code使用最佳实践

wzdushu@gmail.com (wanzi) — Thu, 05 Feb 2026 10:30:00 +0800

Claude Code是Anthropic公司推出的官方AI编程工具，可以读取代码库、编辑文件、运行命令，并与开发工具集成。它在复杂推理和代码理解方面表现优异，是当前最强大的AI编程工具之一。

Claude Code详细介绍

什么是Claude Code

Claude Code是一个由AI驱动的代理编码助手，可以帮助开发者构建功能、修复错误和自动化开发任务。它理解整个代码库，可以跨多个文件和工具工作以完成任务。

核心优势：

强大的代码理解和推理能力
支持终端、VS Code、JetBrains等多种界面
MCP（Model Context Protocol）扩展支持
多代理协作功能
完整的Git工作流集成
支持Claude全系列模型

Claude Code安装

macOS / Linux（推荐）

`1`	`curl -fsSL https://claude.ai/install.sh \| bash`

Windows PowerShell

`1`	`irm https://claude.ai/install.ps1 \| iex`

Windows CMD

`1`	`curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd`

Homebrew

`1`	`brew install --cask claude-code`

WinGet（Windows）

`1`	`winget install Anthropic.ClaudeCode`

VS Code扩展

在VS Code扩展商店搜索"Claude Code"并安装。

快速开始

# 进入项目目录
cd your-project

# 启动Claude Code
claude

# 直接指定任务
claude "帮我创建一个用户登录功能"

Claude Code基础使用

基本使用技巧

1. 任务分解策略

不要一次性让AI完成复杂任务：

# 低效 ❌
claude "帮我写一个完整的电商系统"

# 高效 ✅
claude "帮我设计用户数据表结构"
claude "基于这个结构写用户注册API"
claude "添加登录验证逻辑"

2. 提供完整上下文

# 缺少信息 ❌
claude "这个代码报错"

# 完整信息 ✅
claude "我在用Flask写一个Web服务，登录接口返回500错误。
错误信息：TypeError: Cannot read property 'name' of undefined
堆栈显示发生在app.py第45行。
帮我分析原因并修复。"

3. 使用工具调用

Claude Code可以执行多种操作：

# 读取文件
Read file: src/main.py

# 搜索代码
Grep pattern: "def login" path: src/

# 执行命令
Bash command: python -m pytest

# 写入文件
Write file: src/utils.py

# 批量操作
Glob pattern: "**/*.py"

Claude Code模型选择

Claude Code支持多种Claude模型，可根据任务复杂度选择：

模型	能力	速度	适用场景
Claude Opus 4.6	最高	较慢	复杂架构设计、深度重构
Claude Sonnet 4.6	高	中等	日常开发、代码生成
Claude Haiku 4.5	中等	快	快速补全、简单任务

1
2

# 切换模型
/model claude-sonnet-4-6

Claude Code进阶功能

MCP服务器集成

MCP（Model Context Protocol）可以连接Claude Code到外部工具和数据源：

# 在配置文件中设置MCP服务器
# ~/.claude/config.json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem"],
      "allowedDirectories": ["~/projects"]
    }
  }
}

CLAUDE.md文件

在项目根目录创建CLAUDE.md文件，Claude Code会在每个会话开始时读取：

# 项目说明

## 代码标准
- 使用TypeScript strict模式
- 遵循Airbnb ESLint配置

## 架构决策
- 使用依赖注入模式
- 所有API调用必须包含错误处理

## 首选库
- 状态管理：Zustand
- HTTP客户端：Ky

自定义命令（Skills）

创建可复用的命令模板：

# 创建 /review-pr 命令
# ~/.claude/commands/review-pr.md
# 审查Pull Request

请审查这个PR：
1. 检查代码质量和风格一致性
2. 查找潜在的安全问题
3. 评估测试覆盖是否充分
4. 验证文档是否更新

@pr-url

Hooks配置

在操作前后自动执行shell命令：

# ~/.claude/config.json
{
  "hooks": {
    "PostEdit": [
      {
        "match": "*.ts",
        "command": "npx eslint --fix {file}"
      }
    ]
  }
}

计划任务

# 按计划运行Claude
claude /schedule

# 自动化早晨PR审查
claude /loop 8h /pr review

# 自动化夜间CI失败分析
claude /schedule "0 22 * * *" "分析今天的CI失败"

多代理协作

# 启动多个代理并行工作
claude "启动一个团队来处理这个功能：
- 代理1：前端组件开发
- 代理2：后端API开发
- 代理3：测试编写
协调它们的工作并合并结果"

Git与工作流集成

Git工作流

# 提交更改
claude "commit my changes with a descriptive message"

# 创建分支
claude "创建一个feature分支来实现用户注册功能"

# 分析变更影响
claude "分析当前分支相比main有哪些变更"

代码审查流程

# 1. 让Claude阅读代码
claude "请阅读src目录下所有Python文件，了解项目结构"

# 2. 提出具体审查要求
claude "针对src/api/v1/users.py文件：
- 检查输入验证是否完整
- 查找潜在的安全漏洞
- 评估错误处理是否合理"

# 3. 要求修复建议
claude "针对发现的问题，请逐个提供修复方案"

调试技巧

# 提供错误信息
claude "运行 'python app.py' 时出现以下错误：
TypeError: Cannot read property 'name' of undefined
堆栈信息显示错误发生在第45行。
帮我定位问题并修复。"

# 提供复现步骤
claude "1. 运行 'npm run dev'
2. 访问 http://localhost:3000
3. 点击登录按钮
4. 输入正确凭据后点击提交
期望：登录成功并跳转
实际：页面卡住无响应
控制台显示：Pending POST /api/login"

国产大模型配置

Claude Code原生使用Claude模型，但也支持配置其他国产模型作为替代。

GLM4系列（智谱AI）

智谱GLM系列在中文理解和代码生成方面表现出色。

GLM4.7特点：

超长上下文支持
强大的中文理解能力
代码生成能力强
Tool Calling支持

配置方法：

# 通过MCP配置GLM
# ~/.claude/config.json
{
  "mcpServers": {
    "glm": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-zhipu-api-key",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4"
      }
    }
  }
}

Kimi K2.5（月之暗面）

Kimi K2.5在长上下文和多模态方面有独特优势。

K2.5特点：

256K超长上下文
多模态理解
专业代码生成，编程能力可比肩Claude

定价：

输入：¥4.00/MTok
输出：¥21.00/MTok
缓存命中：¥0.70/MTok

配置方法：

# 通过MCP配置Kimi
# ~/.claude/config.json
{
  "mcpServers": {
    "kimi": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-kimi-api-key",
        "OPENAI_BASE_URL": "https://api.moonshot.cn/v1"
      }
    }
  }
}

MiniMax M2.5

MiniMax M2.5专为编程设计，主打快速响应。

M2.5特点：

高吞吐量、低延迟
专为生产环境优化
编程和Agent能力SOTA
性价比高

配置方法：

# 通过MCP配置MiniMax
# ~/.claude/config.json
{
  "mcpServers": {
    "minimax": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-openai"],
      "env": {
        "OPENAI_API_KEY": "your-minimax-api-key",
        "OPENAI_BASE_URL": "https://api.minimax.chat/v1"
      }
    }
  }
}

与其他AI编程工具对比

Cursor

Cursor是最受欢迎的AI原生IDE之一，被超过一半的Fortune 500企业使用。

与Claude Code对比：

Cursor是完整的AI编辑器，Claude Code是CLI工具
Cursor支持GPT-5、Claude、Gemini等多种模型
Claude Code的推理能力更强，适合复杂任务
Cursor的AI深度集成度更高

Cursor核心功能：

Composer 2：一句话完成多文件修改
Tab智能补全
BugBot自动代码审查
代码库全局理解

Trae

Trae是一款自适应AI IDE，主打本地优先和隐私保护。

与Claude Code对比：

Trae中文界面友好，免费额度充足
Claude Code功能更强大，适合复杂项目
Trae适合国内用户快速上手

Trae核心功能：

Builder模式：对话创建文件
中文界面
隐私保护（不二次训练数据）
MCP协议支持

OpenCode

OpenCode是一款轻量级终端AI编程工具，基于Go语言开发。

与Claude Code对比：

OpenCode更轻量，适合简单任务
Claude Code功能更全面
OpenCode支持更多模型提供商

OpenCode支持模型：

OpenAI: GPT-4.1、GPT-4.5、GPT-4o、O1、O3
Anthropic: Claude 4 Sonnet/Opus、Claude 3.5/3.7 Sonnet
Google: Gemini 2.5、2.5 Flash、2.0 Flash

对比总结

特性	Claude Code	Cursor	Trae	OpenCode
类型	CLI+插件	AI IDE	AI IDE	CLI工具
模型	Claude	多模型	多模型	多模型
推理能力	最强	强	中等	强
中文支持	一般	一般	优秀	一般
学习曲线	中等	低	低	中等
免费额度	有限	有限	充足	依赖API

选择建议：

复杂重构和深度任务 → Claude Code
日常开发和IDE体验 → Cursor
国内用户快速上手 → Trae
轻量级终端任务 → OpenCode

常见问题

Q: Claude Code需要付费吗？

A: Claude Code本身免费，但需要Claude API密钥。新用户有免费额度，订阅用户额度更充足。

Q: 国产模型能否替代Claude？

A: 对于日常编程任务，国产模型已经接近Claude水平。复杂推理任务Claude仍有优势。国产模型价格更便宜。

Q: AI写的代码可以直接用吗？

A: 不可以！AI代码必须经过自己理解、本地测试、代码审查、确认安全后才能使用。

Q: 如何选择Claude模型？

A: 简单任务用Haiku，日常开发用Sonnet，复杂任务用Opus。

总结

Claude Code是当前最强大的AI编程工具之一，特别适合：

复杂的代码理解和重构
多文件批量操作
深度调试和问题分析
需要强大推理能力的任务

通过配置MCP，Claude Code也可以使用国产模型（GLM4、Kimi K2.5、Minimax M2.5）作为替代。根据任务复杂度和预算选择合适的工具和模型。

OpenCode最佳实践：国产大模型编程助手

wzdushu@gmail.com (wanzi) — Thu, 15 Jan 2026 21:22:42 +0800

OpenCode概述

什么是OpenCode

OpenCode是一款开源的AI编程助手，基于VSCode构建，具有以下特点：

开源免费：完全开源，可自建部署
模型灵活：支持多种LLM后端
本地优先：保护代码隐私
高度可定制：可扩展和定制

核心功能

功能	说明
代码补全	实时代码建议（单行/多行）
代码聊天	针对代码进行问答
代码生成	根据描述生成代码
代码解释	解释选中代码的功能
重构建议	提供重构和优化建议
Bug修复	智能修复代码错误

一、OpenCode安装配置

系统要求

操作系统:
  - Windows 10/11
  - macOS 11+
  - Linux (Ubuntu 20.04+, CentOS 8+)

硬件要求:
  - CPU: 4核心+
  - 内存: 8GB+
  - 硬盘: 2GB可用空间

软件依赖:
  - Node.js 16+ (如果从源码构建)
  - Git

安装步骤

方法1：使用预构建版本（推荐）

# 1. 下载OpenCode
# 访问 https://github.com/opencode-org/opencode/releases
# 下载对应平台的安装包

# Linux/macOS
wget https://github.com/opencode-org/opencode/releases/latest/download/opencv-linux-x64.tar.gz
tar -xzf opencv-linux-x64.tar.gz
cd opencv
./opencode

# macOS (使用Homebrew Cask)
brew install --cask opencode

# Windows
# 下载 opencv-setup.exe 并运行安装

# 2. 启动OpenCode
# 首次启动会显示欢迎页面

方法2：从源码构建

# 1. 克隆仓库
git clone https://github.com/opencode-org/opencode.git
cd opencv

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 运行
npm run electron

基础配置

settings.json配置

{
  // OpenCode配置
  "opencode.modelProvider": "openai",
  "opencode.apiKey": "your-api-key",
  "opencode.model": "gpt-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 2048,

  // 代码补全配置
  "opencode.autocomplete.enabled": true,
  "opencode.autocomplete.mode": "inline",
  "opencode.autocomplete.debounce": 150,

  // 代码聊天配置
  "opencode.chat.enabled": true,
  "opencode.chat.contextLength": 10,

  // 隐私配置
  "opencode.telemetry.enabled": false,
  "opencode.anonymousUsageId": false,

  // 快捷键配置
  "opencode.suggestInline": "Ctrl+Enter",
  "opencode.openChat": "Ctrl+Shift+C",
  "opencode.explainCode": "Ctrl+Shift+E"
}

二、OpenCode能做什么

1. 智能代码补全

# 单行补全
def calculate_discount(price, discount_rate):
    return price * (1 - discount_

# OpenCode自动补全:
# rate)

# 多行补全
# 输入注释:
# 创建一个函数，用于计算斐波那契数列的第n项

# OpenCode生成完整函数:
def fibonacci(n):
    """
    计算斐波那契数列的第n项

    Args:
        n (int): 要计算的项数

    Returns:
        int: 第n项的值
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fibonacci(n-1) + fibonacci(n-2)

2. 代码解释

# 选中复杂代码，OpenCode提供解释

def merge_sort(arr):
    if len(arr) <= 1:
        return arr

    mid = len(arr) // 2
    left = merge_sort(arr[:mid])
    right = merge_sort(arr[mid:])

    return merge(left, right)

# OpenCode解释:
# 这是一个归并排序算法的实现。
# 1. 基础情况：如果数组长度<=1，直接返回
# 2. 分治：将数组分成两半，递归排序
# 3. 合并：将两个已排序的数组合并
# 时间复杂度: O(n log n)
# 空间复杂度: O(n)

3. 代码重构

# 原始代码
def process_user(user):
    if user is not None:
        if user.get("name") is not None:
            if user.get("age") is not None and user["age"] >= 18:
                return True
    return False

# OpenCode重构建议:
def process_user(user):
    """
    检查用户是否为有效的成年人

    Args:
        user (dict): 用户信息字典

    Returns:
        bool: 用户是否有效
    """
    if not user:
        return False

    name = user.get("name")
    age = user.get("age")

    return bool(name and age >= 18)

4. Bug检测与修复

# 有bug的代码
def divide_numbers(a, b):
    result = a / b
    return result

# 调用
print(divide_numbers(10, 0))  # ZeroDivisionError

# OpenCode检测并修复:
def divide_numbers(a, b):
    """
    安全地除两个数

    Args:
        a (float): 被除数
        b (float): 除数

    Returns:
        float: 除法结果

    Raises:
        ValueError: 当除数为0时
    """
    if b == 0:
        raise ValueError("除数不能为零")

    return a / b

5. 单元测试生成

# 原始函数
def add(a, b):
    return a + b

# OpenCode生成单元测试:
import unittest

class TestAdd(unittest.TestCase):
    def test_add_positive_numbers(self):
        """测试正数相加"""
        self.assertEqual(add(2, 3), 5)

    def test_add_negative_numbers(self):
        """测试负数相加"""
        self.assertEqual(add(-2, -3), -5)

    def test_add_mixed_numbers(self):
        """测试正负数相加"""
        self.assertEqual(add(2, -3), -1)

    def test_add_zero(self):
        """测试加零"""
        self.assertEqual(add(5, 0), 5)

    def test_add_floats(self):
        """测试浮点数相加"""
        self.assertAlmostEqual(add(2.5, 3.1), 5.6, places=1)

if __name__ == '__main__':
    unittest.main()

三、oh-my-opencode介绍

什么是oh-my-opencode

oh-my-opencode是OpenCode的增强配置管理工具，提供：

预设配置：针对不同场景优化
模型切换：快速切换不同LLM
快捷键绑定：预定义快捷键
主题定制：自定义外观

安装oh-my-opencode

# 1. 克隆仓库
git clone https://github.com/opencode-org/oh-my-opencode.git ~/.oh-my-opencode

# 2. 安装
cd ~/.oh-my-opencode
./install.sh

# 3. 重启OpenCode

预设配置

# 查看可用预设
oh-my-opencode list

# 应用预设
oh-my-opencode apply python-developer
oh-my-opencode apply go-developer
oh-my-opencode apply fullstack-developer

# 创建自定义预设
oh-my-opencode create my-preset --template python-developer

四、国产大模型集成

支持的国产大模型

模型	提供商	特点	推荐场景
GLM-4	智谱AI	中文理解强	中文开发
Minimax M2.5	MiniMax	代码能力强	代码生成
Kimi K2.5	Moonshot	长文本	文档理解
Qwen3.5	阿里云	多语言能力	全栈开发

1. GLM-4配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://open.bigmodel.cn/api/paas/v4/chat/completions",
  "opencode.apiKey": "your-glm-api-key",
  "opencode.model": "glm-4",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 4096,
  "opencode.contextLength": 8192,

  // 请求头配置
  "opencode.customHeaders": {
    "Authorization": "Bearer your-glm-api-key"
  },

  // 响应格式
  "opencode.responseFormat": {
    "type": "text"
  }
}

2. Minimax M2.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.minimax.chat/v1/text/chatcompletion_v2",
  "opencode.apiKey": "your-minimax-api-key",
  "opencode.model": "abab5.5-chat",
  "opencode.temperature": 0.7,
  "opencode.maxTokens": 2048,

  // Minimax特定参数
  "opencode.customParams": {
    "group": "chat_group_name",
    "role_setting": "你是一个专业的编程助手",
    "tokens_to_generate": 2048,
    "temperature": 0.7
  }
}

3. Kimi K2.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://api.moonshot.cn/v1/chat/completions",
  "opencode.apiKey": "your-kimi-api-key",
  "opencode.model": "moonshot-v1-8k",
  "opencode.temperature": 0.3,
  "opencode.maxTokens": 8192,

  // Kimi长上下文配置
  "opencode.contextWindow": 32000,
  "opencode.includeContext": "full"
}

4. Qwen3.5配置

{
  "opencode.modelProvider": "custom",
  "opencode.apiEndpoint": "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions",
  "opencode.apiKey": "your-qwen-api-key",
  "opencode.model": "qwen-plus",
  "opencode.temperature": 0.5,
  "opencode.maxTokens": 6000,

  // Qwen特定参数
  "opencode.customParams": {
    "top_p": 0.8,
    "enable_search": false
  }
}

多模型配置切换

# 创建模型配置文件
~/.opencode/models/
├── glm-4.json
├── minimax-m2.5.json
├── kimi-k2.5.json
└── qwen3.5.json

# 快速切换模型
opencode model switch glm-4
opencode model switch minimax-m2.5
opencode model switch kimi-k2.5
opencode model switch qwen3.5

# 设置默认模型
opencode model default qwen3.5

五、最佳实践

1. Prompt工程

好的Prompt特征

好的Prompt应该：
1. 明确目标 - 清楚说明要做什么
2. 提供上下文 - 给出相关背景信息
3. 指定格式 - 说明期望的输出格式
4. 给出示例 - 提供期望结果的示例
5. 设定约束 - 明确限制条件

示例Prompt

# 差的Prompt
写一个排序函数

# 好的Prompt
请用Python编写一个快速排序函数，要求：
1. 输入：整数列表
2. 输出：排序后的列表
3. 处理边界情况：空列表、单元素列表
4. 包含完整的文档字符串
5. 添加类型注解
6. 包含单元测试示例

请遵循Google Python代码风格指南

2. 上下文管理

# 提供足够的上下文信息

# 不好的示例 - 缺少上下文
# 帮我优化这个函数
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

# 好的示例 - 提供上下文
# 优化以下函数，要求：
# 场景：处理大量传感器数据（百万级）
# 当前性能：处理10万条数据需要5秒
# 目标：处理10万条数据<1秒
# 约束：数据必须保持顺序
# 语言：Python
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

3. 安全最佳实践

安全实践:
  API密钥管理:
    - 使用环境变量存储API密钥
    - 定期轮换密钥
    - 不要提交到代码仓库

  代码审查:
    - AI生成的代码需要人工审查
    - 特别注意安全漏洞
    - 测试边界情况

  敏感信息:
    - 不要让AI访问敏感代码
    - 使用脱敏数据
    - 配置忽略规则

4. 性能优化

{
  // 性能优化配置
  "opencode.cache.enabled": true,
  "opencode.cache.size": "1GB",
  "opencode.cache.ttl": 86400,

  // 请求优化
  "opencode.batchRequests": true,
  "opencode.requestTimeout": 30000,
  "opencode.retryAttempts": 3,

  // 响应缓存
  "opencode.responseCache.enabled": true,
  "opencode.responseCache.maxSize": 500
}

5. 团队协作

团队协作:
  配置共享:
    - 创建团队配置文件
    - 统一模型选择
    - 统一Prompt模板

  版本控制:
    # .opencoderc
    {
      "model": "qwen3.5",
      "temperature": 0.3,
      "presets": {
        "python": "python-dev-preset",
        "go": "go-dev-preset"
      }
    }

  知识库:
    - 维护团队Prompt库
    - 分享最佳实践
    - 定期培训

六、常见问题

Q1: API密钥如何配置

# 方法1：环境变量（推荐）
export OPENCODE_API_KEY="your-api-key"
export OPENCODE_API_ENDPOINT="https://api.example.com"

# 方法2：配置文件
~/.opencode/config.json
{
  "apiKey": "your-api-key",
  "apiEndpoint": "https://api.example.com"
}

# 方法3：OpenCode设置界面
# Settings > OpenCode > API Key

Q2: 如何提高生成质量

{
  // 提高生成质量的配置
  "opencode.temperature": 0.3,        // 降低随机性
  "opencode.topP": 0.9,               // 控制多样性
  "opencode.frequencyPenalty": 0.5,   // 减少重复
  "opencode.presencePenalty": 0.3,    // 鼓励新话题

  // 增加上下文
  "opencode.contextLines": 50,        // 增加上下行数
  "opencode.includeFileHeader": true,  // 包含文件头
  "opencode.includeImports": true     // 包含导入
}

Q3: 离线使用方案

离线方案:
  本地模型:
    - 使用Ollama运行本地模型
    - 支持Llama、CodeLlama等
    - 配置本地API端点

  配置:
    opencode.apiEndpoint: "http://localhost:11434"
    opencode.model: "codellama:13b"

总结

OpenCode作为开源AI编程助手，具有以下优势：

开源免费：无订阅费用
模型灵活：支持多种LLM后端
国产模型：集成GLM、Minimax、Kimi、Qwen
可定制：高度可配置
隐私保护：本地部署选项

配合oh-my-opencode和国产大模型，可以构建高效的AI辅助开发环境。

基于OpenObserve和Fluent Bit搭建企业日志服务平台

wzdushu@gmail.com (wanzi) — Wed, 12 Nov 2025 09:30:00 +0800

平台架构

技术选型

OpenObserve（原名O2）是一款开源的可观测性平台，相比传统ELK方案具有显著优势：

资源占用低：内存占用仅为Elasticsearch的1/10，存储空间节省90%
高性能：基于Rust编写，单节点可处理5TB+日志/天
全功能：集成日志、指标、链路追踪，替代Grafana+Loki+Tempo
兼容性强：支持Elasticsearch API、Prometheus API、OpenTelemetry
部署简单：单一二进制文件，无外部依赖

Fluent Bit是云原生日志收集器：

轻量级：内存占用<1MB，适合嵌入式和容器环境
高性能：多线程异步处理，吞吐量可达100MB/s
丰富插件：支持200+输入/输出/过滤/解析器
Kubernetes原生：自动发现Pod、标签注入、元数据关联

架构设计

┌─────────────────────────────────────────────────────────────────┐
│                        业务应用层                                 │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │  Java应用 │  │  Go服务  │  │ Nginx日志 │  │ 系统日志  │       │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘       │
│       │             │             │             │               │
│  stdout/stderr   stdout/stderr  /var/log/*   /var/log/*         │
└───────┼─────────────┼─────────────┼─────────────┼───────────────┘
        │             │             │             │
┌───────┴─────────────┴─────────────┴─────────────┴───────────────┐
│                      Kubernetes集群                              │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              DaemonSet: Fluent Bit                      │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │   │
│  │  │  Tail输入    │→ │  过滤/解析   │→ │  Buffer缓冲  │  │   │
│  │  └──────────────┘  └──────────────┘  └──────────────┘  │   │
│  └─────────────────────────────────────────────────────────┘   │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTP/HTTPS
┌──────────────────────────────┴──────────────────────────────────┐
│                    OpenObserve集群                               │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │  Ingest节点  │→ │  数据存储    │→ │  查询引擎    │          │
│  │  (写入优化)  │  │  (Parquet)   │  │  (全文检索)  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

组件版本

组件	版本	说明
OpenObserve	0.15.0+	稳定版，支持分布式
Fluent Bit	4.0.0+	最新稳定版
Kubernetes	1.24+	生产环境
Helm	3.0+	部署工具

OpenObserve部署

前置准备

# 1. 创建Namespace
kubectl create namespace logging

# 2. 添加OpenObserve Helm仓库
helm repo add openobserve https://charts.openobserve.ai
helm repo update

# 3. 创建PV/PVC（生产环境使用分布式存储）
cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: openobserve-data
  namespace: logging
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: zstack-rbd  # 根据实际SC调整
  resources:
    requests:
      storage: 500Gi
EOF

Helm部署OpenObserve

创建values文件 openobserve-values.yaml：

# openobserve-values.yaml

image:
  repository: public.ecr.aws/zinclabs/openobserve
  tag: "0.15.1"
  pullPolicy: IfNotPresent

replicaCount: 3  # 生产环境建议3节点高可用

# 资源配置（根据日志量调整）
resources:
  limits:
    cpu: "8"
    memory: 16Gi
  requests:
    cpu: "4"
    memory: 8Gi

# 数据持久化
persistence:
  enabled: true
  existingClaim: openobserve-data
  mountPath: /data

# 环境变量
env:
  - name: ZO_ROOT_USER_EMAIL
    value: "admin@example.com"
  - name: ZO_ROOT_USER_PASSWORD
    valueFrom:
      secretKeyRef:
        name: openobserve-secret
        key: password
  - name: ZO_DATA_DIR
    value: "/data"
  - name: ZO_HTTP_PORT
    value: "5080"
  - name: ZO_MEMORY_CACHE_ENABLED
    value: "true"
  - name: ZO_MEMORY_CACHE_MAX_SIZE
    value: "4096"  # MB
  - name: ZO_COMPRESSION_ENABLED
    value: "true"
  - name: ZO_COMPRESSION_FORMAT
    value: "zstd"
  - name: ZO_PARquet_COMPRESSION
    value: "zstd"
  - name: ZO_META_STORE
    value: "sqlite"  # 生产环境使用PostgreSQL
  - name: ZO_METRICS_ENABLED
    value: "true"

# 配置PostgreSQL元数据库（生产环境推荐）
envFrom:
  - secretRef:
      name: postgres-connection

# Service配置
service:
  type: ClusterIP
  port: 5080
  targetPort: 5080
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"

# Ingress配置
ingress:
  enabled: true
  className: "nginx"
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"
    nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
  hosts:
    - host: logs.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: logs-tls
      hosts:
        - logs.example.com

# Pod调度
nodeSelector: {}
tolerations: []
affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - openobserve
          topologyKey: kubernetes.io/hostname

# 监控配置
monitoring:
  enabled: true
  serviceMonitor:
    enabled: true
    interval: 30s
    namespace: logging

部署OpenObserve

# 1. 创建密码Secret
kubectl create secret generic openobserve-secret \
  --from-literal=password='your-secure-password' \
  -n logging

# 2. 部署
helm upgrade --install openobserve openobserve/openobserve \
  -n logging \
  -f openobserve-values.yaml \
  --version 0.10.2 \
  --timeout 15m

# 3. 等待Pod就绪
kubectl wait --for=condition=ready pod \
  -l app.kubernetes.io/name=openobserve \
  -n logging \
  --timeout=300s

# 4. 查看状态
kubectl get pods -n logging
kubectl logs -f deployment/openobserve -n logging

# 5. 访问Web UI
echo "访问地址: https://logs.example.com"
echo "默认用户: admin@example.com"

Fluent Bit部署

安装 Helm Chart

helm repo add fluent https://fluent.github.io/helm-charts
helm repo update
helm pull fluent/fluent-bit --version 0.50.0
helm install fluent-bit ./fluent-bit-0.50.0.tgz --namespace uganda-prod

调整 DaemonSet 配置

spec:
  volumes:
    - name: config
      configMap:
        name: fluent-bit
        defaultMode: 420
  containers:
    resources:
      requests:
        cpu: "1"
        memory: 2Gi
      limits:
        cpu: "2"
        memory: 4Gi
    volumeMounts:
      - name: config
        mountPath: /fluent-bit/etc/conf/custom_parsers.conf
        subPath: custom_parsers.conf
      - name: config
        mountPath: /fluent-bit/etc/conf/multiline_parsers.conf
        subPath: multiline_parsers.conf

Fluent Bit采集规则调整

完整ConfigMap 配置

kind: ConfigMap
apiVersion: v1
metadata:
  name: fluent-bit-config
  namespace: uganda-prod
  labels:
    app: fluent-bit
    tier: logging
data:
  # ---------------------------------------------------------------------------
  # 1. 自定义解析器 (Custom Parsers)
  # 用于提取特定格式的日志字段，例如从 Java 日志中提取日志级别 (INFO, ERROR 等)
  # ---------------------------------------------------------------------------
  custom_parsers.conf: |
    [PARSER]
        Name        java_log_level
        Format      regex
        # 匹配格式: 2023-10-27 10:00:00.123 INFO ...
        # 捕获组 'level' 将包含日志级别
        Regex       ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}\s+(?<level>[A-Z]+)

  # ---------------------------------------------------------------------------
  # 2. 多行解析器 (Multiline Parsers)
  # 专门用于处理 Java 堆栈跟踪等多行日志，防止堆栈被拆分成多条记录
  # ---------------------------------------------------------------------------
  multiline_parsers.conf: |
    [MULTILINE_PARSER]
        Name          java_md_multiline
        Type          regex
        # 规则 1: 如果行以日期开头 (如 2023-...)，视为新日志的开始
        rule      "start_state"   "/^\d{4}-\d{2}-\d{2}/"           "cont"
        # 规则 2: 如果行不以日期开头，视为上一行的延续 (堆栈部分)
        rule      "cont"        "/^(?!\d{4}-\d{2}-\d{2}).+/"     "cont"
        # 刷新超时时间 (秒)，超时后强制输出当前缓冲的多行日志
        flush_timeout 5

  # ---------------------------------------------------------------------------
  # 3. 主配置文件 (Main Configuration)
  # ---------------------------------------------------------------------------
  fluent-bit.conf: |
    [SERVICE]
        Daemon              Off
        Flush               1
        Log_Level           info
        # 加载标准解析器和自定义解析器
        Parsers_File        /fluent-bit/etc/conf/parsers.conf
        Parsers_File        /fluent-bit/etc/conf/custom_parsers.conf
        Parsers_File        /fluent-bit/etc/conf/multiline_parsers.conf
        
        # 开启内置 HTTP 服务器，用于健康检查和指标暴露 (/api/v1/metrics)
        HTTP_Server         On
        HTTP_Listen         0.0.0.0
        HTTP_Port           2020
        Health_Check        On

        # 文件系统缓冲配置 (防止后端不可用时丢失数据)
        storage.path              /var/log/flb_storage
        storage.sync              normal
        storage.checksum          off
        storage.backlog.mem_limit 200M

    # -----------------------------------------------------------------------
    # [INPUT] 尾随文件采集
    # 采集 Docker/Containerd 生成的标准容器日志
    # -----------------------------------------------------------------------
    [INPUT]
        Name                tail
        Path                /var/log/containers/*.log
        # 启用内置的多行解析 (docker, cri 格式)
        multiline.parser    docker, cri
        Tag                 kube.*
        Mem_Buf_Limit       500MB
        Skip_Long_Lines     On
        Refresh_Interval    10
        # 持久化偏移量数据库，重启后从断点继续读取
        DB                  /var/log/flb_kube.db
        DB.Sync             Normal
        Rotate_Wait         30
        Read_from_Head      Off

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 1: 多行合并
    # 在获取 K8s 元数据之前先合并多行日志，确保堆栈跟踪作为单条记录处理
    # -----------------------------------------------------------------------
    [FILTER]
        Name                multiline
        Match               kube.*
        multiline.key_content log
        multiline.parser    java_md_multiline

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 2: K8s 元数据增强
    # 调用 K8s API 获取 Pod 详细信息 (Namespace, Pod Name, Labels 等)
    # -----------------------------------------------------------------------
    [FILTER]
        Name                kubernetes
        Match               kube.*
        Merge_Log           Off       # 不尝试解析 log 字段为 JSON (避免性能开销或错误)
        Keep_Log            On        # 保留原始 log 字段
        K8S-Logging.Parser  On        # 允许 Pod Annotation 指定 parser
        K8S-Logging.Exclude Off       # 不排除带有特定 annotation 的日志

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 3: 日志内容解析
    # 使用自定义解析器提取 'level' 字段
    # -----------------------------------------------------------------------
    [FILTER]
        Name                parser
        Match               kube.*
        Key_Name            log
        Parser              java_log_level
        Reserve_Data        On        # 保留原始数据
        Preserve_Key        On        # 保留原始 log 键

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 4: 字段初步清洗
    # 复制提取的 level 字段，移除不需要的临时字段
    # -----------------------------------------------------------------------
    [FILTER]
        Name                modify
        Match               kube.*
        Copy                level level
        Remove              _p
        Remove              stream
        Remove              time

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 5: 结构重组 (Nest Lift)
    # 将 kubernetes 对象下的字段提升到顶层，并添加前缀 'k8s_'
    # 目的：扁平化数据结构，便于后续规则匹配
    # -----------------------------------------------------------------------
    [FILTER]
        Name                nest
        Match               kube.*
        Operation           lift
        Nested_under        kubernetes
        Add_prefix          k8s_

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 6: 移除冗余元数据
    # 删除不需要发送到后端的庞大字段 (如 annotations, docker_id)
    # -----------------------------------------------------------------------
    [FILTER]
        Name                modify
        Match               kube.*
        Remove              k8s_annotations
        Remove              k8s_docker_id
        Remove              k8s_container_hash

    # -----------------------------------------------------------------------
    # [FILTER] 阶段 7: 结构重组 (Nest Nest)
    # 将所有 'k8s_' 前缀的字段重新打包回 'kubernetes' 对象下，去除前缀
    # 目的：恢复整洁的嵌套结构，同时已清理了无用字段
    # -----------------------------------------------------------------------
    [FILTER]
        Name                nest
        Match               kube.*
        Operation           nest
        Wildcard            k8s_*
        Nested_under        kubernetes
        Remove_prefix       k8s_

    # =======================================================================
    # [FILTER] 阶段 8: 动态路由 (Rewrite Tag) - 第一跳：按环境分流
    # 根据 Namespace 名称修改 Tag，将日志引导至不同的处理流
    # 语法: Rule $字段名 正则表达式 新Tag 保持原记录(布尔)
    # =======================================================================
    
    # 路由：uganda-uat 环境
    [FILTER]
        Name                rewrite_tag
        Match               kube.*
        Rule                $kubernetes['namespace_name'] ^uganda-uat$ uganda-uat.temp false
        Emitter_Name        re_emitted_uganda-uat-temp

    # 路由：uganda-test 环境
    [FILTER]
        Name                rewrite_tag
        Match               kube.*
        Rule                $kubernetes['namespace_name'] ^uganda-test$ uganda-test.temp false
        Emitter_Name        re_emitted_uganda-test-temp

    # 路由：uganda-prod 环境 (当前部署命名空间)
    [FILTER]
        Name                rewrite_tag
        Match               kube.*
        Rule                $kubernetes['namespace_name'] ^uganda-prod$ uganda-prod.temp false
        Emitter_Name        re_emitted_uganda-prod-temp

    # 路由：uganda-offline 环境
    [FILTER]
        Name                rewrite_tag
        Match               kube.*
        Rule                $kubernetes['namespace_name'] ^uganda-offline$ uganda-offline.temp false
        Emitter_Name        re_emitted_uganda-offline-temp

    # =======================================================================
    # [FILTER] 阶段 9: 动态路由 (Rewrite Tag) - 第二跳：按服务分流
    # 针对特定环境的特定容器进行二次分流，实现细粒度索引隔离
    # =======================================================================

    # 示例：UAT 环境 -> lms-backend 服务
    [FILTER]
        Name                rewrite_tag
        Match               uganda-uat.temp
        Rule                $kubernetes['container_name'] ^lms-backend$ uganda-uat-lms-backend false
        Emitter_Name        re_emitted_uganda-uat-lms-backend

    # 示例：UAT 环境 -> other-service 服务 (需补充完整配置)
    [FILTER]
        Name                rewrite_tag
        Match               uganda-uat.temp
        Rule                $kubernetes['container_name'] ^other-service$ uganda-uat-other-service false
        Emitter_Name        re_emitted_uganda-uat-other-service

    # 注意：Production 和其他环境需要类似地添加对应的容器名过滤规则
    # 例如：
    # [FILTER]
    #     Name rewrite_tag
    #     Match uganda-prod.temp
    #     Rule $kubernetes['container_name'] ^payment-service$ uganda-prod-payment-service false
    #     Emitter_Name re_emitted_uganda-prod-payment-service

    # =======================================================================
    # [OUTPUT] 输出插件配置
    # 将经过路由筛选的日志发送到 OpenObserve
    # =======================================================================

    # 输出：UAT LMS Backend
    [OUTPUT]
        Name                http
        Match               uganda-uat-lms-backend
        URI                 /api/39NVPcXSEBOwGM5UnceQ35hQFNB/lms_backend/_json
        Host                openobserve.uganda-uat.svc.cluster.local
        Port                5080
        tls                 Off
        Format              json
        Json_date_key       _timestamp
        Json_date_format    iso8601
        
        HTTP_User           ops@test.com
        HTTP_Passwd         ROPe50N4BJjovJiT 
        
        compress            gzip
        Retry_Limit         False       # 无限重试直到成功
        net.connect_timeout 10
        net.io_timeout      30

    # 输出：UAT Other Service (示例)
    [OUTPUT]
        Name                http
        Match               uganda-uat-other-service
        URI                 /api/39NVPcXSEBOwGM5UnceQ35hQFNB/other_service/_json
        Host                openobserve.uganda-uat.svc.cluster.local
        Port                5080
        tls                 Off
        Format              json
        Json_date_key       _timestamp
        Json_date_format    iso8601
        HTTP_User           devops@test.com
        HTTP_Passwd         ROPe50N4BJjovJiT
        compress            gzip
        Retry_Limit         False

    # 默认输出 (可选): 捕获未匹配任何特定规则的日志，防止数据丢失
    # [OUTPUT]
    #     Name http
    #     Match uganda-prod.temp
    #     URI /api/.../default/_json
    #     ...

配置说明

Filter 阶段: 使用 rewrite_tag 过滤器按 Namespace 和容器名称过滤日志
Output 阶段: 将过滤后的日志通过 HTTP 发送到不同环境下的OpenObserve
多行日志: 使用 multiline 过滤器处理 Java 异常堆栈
日志优化: gzip 压缩、失败重试、TCP 超时配置

多行合并规则说明

状态	匹配规则	说明
start_state	`/^\d{4}-\d{2}-\d{2}/`	以日期开头 → 新日志开始，进入 cont 状态
cont	`/^(?!\d{4}-\d{2}-\d{2}).+/`	不以日期开头 → 继续拼接到上一条日志

注意: 修改完 ConfigMap 后需要重启 fluent-bit 服务

数据管理

创建数据流

# 方法1：通过API创建
curl -X POST "https://logs.example.com/api/demo/streams" \
  -u "admin@example.com:password" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "app-logs",
    "storage_type": "memory",
    "stream_type": "logs"
  }'

# 方法2：自动创建（首次写入自动创建,我们这里采用这种方式）
# Fluent Bit写入新stream会自动创建

设置数据保留策略

openobserve的dashboard里可以基于索引设置保留策略,主要策略如下:

基于时间保留
基于大小保留
混合策略（3650天或30TB，先到为准，这里我们采用这种方式，由于业务为金融服务，故设置保留10年）

数据归档配置

# 启用S3归档
env:
  - name: ZO_S3_STORE_ENABLED
    value: "true"
  - name: ZO_S3_STORE_BUCKET
    value: "logs-archive"
  - name: ZO_S3_STORE_REGION
    value: "us-east-1"
  - name: ZO_S3_STORE_ACCESS_KEY
    valueFrom:
      secretKeyRef:
        name: s3-credentials
        key: access-key
  - name: ZO_S3_STORE_SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: s3-credentials
        key: secret-key

数据压缩

# OpenObserve自动压缩
env:
  - name: ZO_COMPRESSION_ENABLED
    value: "true"
  - name: ZO_COMPRESSION_FORMAT
    value: "zstd"  # zstd/gzip/snappy
  - name: ZO_COMPRESSION_LEVEL
    value: "3"  # 1-19，越高压缩率越高但CPU消耗越大

查询与分析

OpenObserve 提供强大的查询引擎，支持 SQL 模式和原生查询语言 (VQL)。以下介绍基本查询和聚合查询在不同场景下使用，帮助您快速定位关键日志。

💡 核心提示

模式切换：聚合查询建议在 SQL 模式 下执行。

表名规范：Stream 名称（表名）必须用双引号包裹，例如 "lms"。

时间范围：所有查询均受 UI 右上角时间选择器的限制，请确保时间范围覆盖目标数据。

1. 基础检索 (Basic Search)

快速定位单条日志或特定事件。

1.1 全文索引搜索

自动扫描所有文本字段，适合模糊查找。

`1`	`match_all('timeout')`

场景：不确定错误出现在哪个字段，快速全局搜索关键词。

1.2 指定字段搜索

针对特定字段进行精确或包含匹配，性能更优。

`1`	`str_match(log, 'tenant-backend')`

场景：筛选特定服务（如 tenant-backend）或特定级别（str_match(level, 'ERROR')）的日志。

1.3 多条件组合查询

使用逻辑运算符 (AND, OR, NOT) 构建复杂过滤规则。

1
2

(level = 'INFO' OR level = 'ERROR') 
AND str_match(log, 'AuthInterceptor')

场景：只看认证模块的日志，且包含正常流程和报错流程。

2. 聚合查询 (Aggregation Queries) 🚀

通过 SQL 的 GROUP BY 和聚合函数 (COUNT, SUM, AVG, MAX, MIN)，将海量日志转化为统计图表数据。

2.1 按日志级别统计 (Count by Level)

统计不同日志级别的数量，快速判断系统健康度。

SELECT level, COUNT(*) as log_count 
FROM "lms" 
GROUP BY level 
ORDER BY log_count DESC

输出示例：

level log_count

INFO 15420

ERROR 32

WARN 105

2.2 按时间窗口趋势分析 (Time Series Histogram)

结合 date_trunc 函数，统计单位时间内的日志量，用于绘制趋势图。

SELECT date_trunc('minute', _timestamp) as time_window, COUNT(*) as hits
FROM "lms"
WHERE str_match(log, 'payment')
GROUP BY time_window
ORDER BY time_window ASC

场景：观察“支付”相关日志在每分钟内的波动情况，定位突发流量或故障时间点。
注意：'minute' 可替换为 'hour', 'day' 等。

2.3 按服务/容器分组统计 (Group by Service)

分析哪个微服务产生的日志最多或错误最多。

SELECT kubernetes.container_name, COUNT(*) as total_logs
FROM "lms"
WHERE level = 'ERROR'
GROUP BY kubernetes.container_name
ORDER BY total_logs DESC
LIMIT 5

场景：找出当前产生错误最多的前 5 个容器，优先排查。

2.4 多维度交叉分析 (Multi-Dimension Analysis)

同时按两个或多个维度分组，进行深度下钻分析。

SELECT 
  date_trunc('hour', _timestamp) as hour,
  level,
  COUNT(*) as count
FROM "lms"
WHERE str_match(log, 'database')
GROUP BY hour, level
ORDER BY hour ASC, level

场景：查看每小时中，数据库相关日志的 INFO 和 ERROR 分布变化。

2.5 数值字段统计 (Numeric Aggregation)

如果日志中包含提取出的数值字段（如响应时间 duration），可进行数学计算。

SELECT 
  AVG(duration) as avg_latency,
  MAX(duration) as max_latency,
  MIN(duration) as min_latency
FROM "lms"
WHERE str_match(log, 'API_REQUEST')

场景：计算特定 API 请求的平均耗时、最大耗时，评估性能瓶颈。

3. 高级技巧与最佳实践

技巧	说明	示例
限制结果集	避免返回过多数据导致浏览器卡顿	添加 `LIMIT 100`
去重统计	统计唯一的错误消息种类	`COUNT(DISTINCT log)`
别名优化	让输出列名更易读	`COUNT(*) as "错误总数"`
空值处理	排除字段为空的记录	`WHERE level IS NOT NULL`
正则匹配	比 `str_match` 更灵活的匹配	`REGEXP_MATCH(log, 'Error.*\d+')`

⚠️ 性能建议

先过滤后聚合：务必在 WHERE 子句中尽可能缩小数据范围（如指定时间、关键字），再进行 GROUP BY，能显著提升查询速度。
时间粒度：在大时间范围（如 7 天）查询时，使用 date_trunc('hour', ...) 或 date_trunc('day', ...)，避免使用 'second' 导致数据点过多。
字段索引：对常用于 GROUP BY 的字段（如 level, container_name），建议在 Stream Settings 中开启索引以获得最佳性能。

OpenObserve优化

# 内存缓存
env:
  - name: ZO_MEMORY_CACHE_ENABLED
    value: "true"
  - name: ZO_MEMORY_CACHE_MAX_SIZE
    value: "8192"  # 8GB

# 查询缓存
  - name: ZO_QUERY_CACHE_ENABLED
    value: "true"
  - name: ZO_QUERY_CACHE_MAX_SIZE
    value: "4096"  # 4GB

# 并行查询
  - name: ZO_QUERY_WORKER_THREADS
    value: "8"

存储优化

# Parquet列式存储
env:
  - name: ZO_PARQUET_COMPRESSION
    value: "zstd"
  - name: ZO_PARQUET_ROW_GROUP_SIZE
    value: "1048576"  # 1MB

# 数据分区
  - name: ZO_PARTITION_ENABLED
    value: "true"
  - name: ZO_PARTITION_FIELDS
    value: "_timestamp,kubernetes.namespace_name"

监控告警

这里有两个部分需要做监控，一部分是Openobserve本身服务监控，一部分是业务日志监控,对于Openobseve和fluentbit服务本身的监控直接采用Prometheus监控即可,对于核心业务订单日志监控直接采用Openobserve自带告警机制即可满足。

Prometheus指标采集

# Fluent Bit ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: fluent-bit
  namespace: logging
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: fluent-bit
  endpoints:
    - port: metrics
      interval: 30s

# OpenObserve ServiceMonitor
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: openobserve
  namespace: logging
spec:
  selector:
    matchLabels:
      app.kubernetes.io/name: openobserve
  endpoints:
    - port: http
      path: /metrics
      interval: 30s

告警规则

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: logging-alerts
  namespace: logging
spec:
  groups:
    - name: logging
      rules:
        # Fluent Bit日志丢失告警
        - alert: FluentBitLogsDropping
          expr: rate(fluentbit_output_proc_records_failed_total[5m]) > 100
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "Fluent Bit日志丢失"
            description: "过去5分钟丢失{{ $value }}条日志"

        # OpenObserve存储告警
        - alert: OpenObserveDiskSpaceLow
          expr: (node_filesystem_avail_bytes{mountpoint="/data"} / node_filesystem_size_bytes{mountpoint="/data"}) < 0.1
          for: 10m
          labels:
            severity: critical
          annotations:
            summary: "OpenObserve存储空间不足"
            description: "剩余空间不足10%"

        # 日志摄入延迟
        - alert: LoggingIngestLag
          expr: openobserve_ingest_delay_seconds > 300
          for: 5m
          labels:
            severity: warning
          annotations:
            summary: "日志摄入延迟"
            description: "日志延迟{{ $value }}秒"

业务日志告警

涉及如下几个关键部分:

告警消息模版

设置–> 模版 –>添加模版，定义Webhook告警消息格式, 注意这里的消息需要根据不同的聊天工具

新建\:cdi-prod-template

    {
      "msgtype": "text",
      "text": {
        "content": "🚨 【告警通知】\n告警名称: {alert_name}\n流名称: {stream_name}\n严重程度: Error\n日志信息: {rows:1}\n触发时间: {alert_trigger_time_str}"
      }
    }

注意: 这里的消息需要根据不同的聊天工具配置有差异，我这里的配置是企业微信配置，更多请参考https://openobserve.ai/docs/user-guide/management/templates/ 这里配置自己适合的告警模版

告警地址

通过企业微信群组添加消息助手，获取推送消息Webhook地址,然后Openobserve UI 设置–> 地址 –>添加地址即可.

告警规则配置

这个需要根据内部研发团队沟通，业务日志匹配规则，日常告警只匹配Erorr级别即可，对于核心订单和风控流程建议添加上电话告警:

OpenObserve开源版风险与注意事项

RBAC权限控制

开源版限制：

无细粒度的RBAC控制（企业版支持）
所有用户拥有相同权限
无法按组织/项目隔离数据

解决方案：

# 1. 使用多租户（Stream级别隔离）
# 为每个团队创建独立的Stream
curl -X POST "https://logs.example.com/api/demo/streams" \
  -d '{"name":"team-a-logs"}'
curl -X POST "https://logs.example.com/api/demo/streams" \
  -d '{"name":"team-b-logs"}'

# 2. 使用反向代理做权限控制
# Nginx根据用户路由到不同Stream
location /api/team-a/ {
  internal;
  proxy_pass http://openobserve.logging.svc/api/team-a-logs/;
}

# 3. 使用API Key做简单鉴权
# 为每个团队生成独立的API Key

这里由于项目比较多，通常在反向代理添加权限控制规则，比如限制Post请求的IP、和Host

数据安全

风险点：

开源版无字段级加密
敏感信息可能明文存储
缺少审计日志

最佳实践：

# 1. Fluent Bit脱敏
[FILTER]
    Name                modify
    Match               kube.*
    Remove              password,token,secret,key,ssn
    Rename              message  log_message

# 2. 使用Lua过滤器脱敏
[FILTER]
    Name                lua
    Match               kube.*
    Script              mask.lua
    Call                mask_sensitive

# mask.lua:
function mask_sensitive(tag, timestamp, record)
    if record["message"] ~= nil then
        record["message"] = string.gsub(record["message"], "password=%S+", "password=***")
    end
    return 1, timestamp, record
end

高可用风险

单点故障：

开源版无自动故障转移
节点宕机可能导致数据丢失

解决方案：

# 1. 部署多副本
replicaCount: 3

# 2. 使用共享存储
persistence:
  enabled: true
  storageClass: "nfs-client"  # 使用分布式存储,我这里底层采用的Ceph的RBD

# 3. 配置Pod反亲和性
affinity:
  podAntiAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      - labelSelector:
          matchExpressions:
            - key: app.kubernetes.io/name
              operator: In
              values:
                - openobserve
        topologyKey: kubernetes.io/hostname

容量规划

日志量	Fluent Bit资源	OpenObserve资源	存储空间/月
10GB/天	100m CPU / 100Mi	2 CPU / 4Gi	100GB
100GB/天	200m CPU / 200Mi	4 CPU / 8Gi	1TB
1TB/天	500m CPU / 500Mi	8 CPU / 16Gi	10TB

总结

基于OpenObserve和Fluent Bit的日志平台方案具有以下优势：

成本优势：相比ELK方案，存储成本降低90%，计算资源降低70%
高性能：单节点支持5TB+/天日志摄入，查询响应<100ms
简单易用：部署时间<30分钟，学习成本低
云原生：Kubernetes原生集成，支持自动扩缩容

已在生产环境稳定运行半年，数据量5TB+，查询响应稳定在200ms以内，基本满足了大部分业务需求，如果对RBAC有强需求的建议直接购买商业版或者放弃本方案。

Kustomize私有化部署多场景多环境容器服务

wzdushu@gmail.com (wanzi) — Sat, 25 Oct 2025 10:30:00 +0800

早期一直在使用helm或者kubectl原生yaml结合CI和ArgoCD部署应用，最近在给一个金融大客户部署私有化服务的时候，发现客户的环境比较复杂，涉及多个国家多套环境，比如Test、UAT、Prod，差不多有三十个环境，每次修改的values和yaml文件快吐了，这次打算用Kustomize来改造现有的部署应用试试。

Kustomize介绍

什么是Kustomize

Kustomize是Kubernetes原生的配置管理工具，通过模板化的方式管理YAML资源：

核心特性：

无模板语法，纯YAML
声明式配置管理
支持多环境管理
GitOps友好
已集成kubectl 1.14+

与Helm对比：

特性	Kustomize	Helm
模板语法	无（纯YAML）	Go Template
学习曲线	低	中高
多环境管理	Base + Overlay	Values文件
包管理	无	Chart Repository
版本管理	Git	Chart版本
适合场景	应用开发者	应用分发者

基本概念

kustomization.yaml
├── bases/          # 基础配置（复用）
├── overlays/       # 环境覆盖
│   ├── dev/
│   ├── staging/
│   └── prod/
├── patches/        # 配置补丁
└── resources/      # 静态资源

Kustomize与Helm区别

设计理念

Kustomize设计理念：

# 声明式配置管理
# 不使用模板，而是通过叠加（Overlay）方式修改配置

# Base: 基础配置
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 1
  template:
    spec:
      containers:
        - name: app
          image: my-app:latest

# Overlay: 环境差异
# overlays/production/kustomization.yaml
bases:
  - ../../base
patchesStrategicMerge:
  - |-
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: my-app
    spec:
      replicas: 10

Helm设计理念：

# 模板化配置管理
# 使用Go Template模板

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: app
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

# values.yaml (不同环境不同values)
replicaCount: 1
image:
  repository: my-app
  tag: latest

# values-production.yaml
replicaCount: 10
image:
  repository: my-app
  tag: v1.2.3

功能对比

功能	Kustomize	Helm
模板	无模板，纯YAML	Go Template
学习曲线	低，只需会YAML	中高，需学模板语法
复用性	Base + Overlay	Chart + Values
调试	kubectl kustomize	helm template –dry-run
版本管理	Git版本控制	Chart版本号
环境管理	Overlay目录	多个Values文件
包分发	无（用Git）	Chart仓库
CI/CD集成	原生kubectl	需安装helm
Rollback	kubectl rollout	helm rollback
依赖管理	无直接支持	Chart dependencies

适用场景

选择Kustomize的场景：

应用开发者管理自己的K8s资源
需要GitOps工作流
多环境配置差异大
不想学习模板语言
团队熟悉YAML和kubectl

选择Helm的场景：

应用分发者（软件供应商）
需要包管理和版本控制
配置相对固定
复杂的应用依赖关系
快速部署第三方应用

Kustomize部署K8s应用

项目结构

my-app/
├── base/                           # 基础配置
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── configmap.yaml
│   ├── serviceaccount.yaml
│   └── kustomization.yaml
├── overlays/                       # 环境配置
│   ├── dev/
│   │   ├── kustomization.yaml
│   │   ├── deployment-replica.yaml
│   │   ├── deployment-resources.yaml
│   │   └── configmap-env.yaml
│   ├── staging/
│   │   ├── kustomization.yaml
│   │   └── deployment-replica.yaml
│   └── production/
│       ├── kustomization.yaml
│       ├── deployment-replica.yaml
│       ├── deployment-resources.yaml
│       └── configmap-prod.yaml
└── scripts/
    └── deploy.sh

Base配置创建

base/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
  labels:
    app: my-app
    version: v1.0.0
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-app
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: my-app
        version: v1.0.0
    spec:
      serviceAccountName: my-app
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 1000
      containers:
        - name: my-app
          image: my-app:latest
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 8080
              protocol: TCP
          env:
            - name: JAVA_OPTS
              value: "-Xms512m -Xmx512m"
            - name: SPRING_PROFILES_ACTIVE
              value: "prod"
          resources:
            requests:
              cpu: 100m
              memory: 512Mi
            limits:
              cpu: 500m
              memory: 1Gi
          livenessProbe:
            httpGet:
              path: /actuator/health/liveness
              port: 8080
            initialDelaySeconds: 60
            periodSeconds: 10
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /actuator/health/readiness
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 5
            timeoutSeconds: 3
            failureThreshold: 3
          volumeMounts:
            - name: config
              mountPath: /config
            - name: logs
              mountPath: /logs
      volumes:
        - name: config
          configMap:
            name: my-app-config
        - name: logs
          emptyDir: {}

base/service.yaml

apiVersion: v1
kind: Service
metadata:
  name: my-app
  labels:
    app: my-app
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: http
      protocol: TCP
      name: http
  selector:
    app: my-app

base/configmap.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-app-config
data:
  application.yml: |
    server:
      port: 8080
    spring:
      application:
        name: my-app
    logging:
      level:
        root: INFO

base/serviceaccount.yaml

apiVersion: v1
kind: ServiceAccount
metadata:
  name: my-app

base/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 引用的资源文件
resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml
  - serviceaccount.yaml

# 通用标签（所有资源添加）
commonLabels:
  app.kubernetes.io/name: my-app
  app.kubernetes.io/instance: my-app
  app.kubernetes.io/managed-by: kustomize
  app.kubernetes.io/version: v1.0.0

# 通用注解
commonAnnotations:
  createdBy: kustomize
  env: base

# 名称前缀
# namePrefix: dev-

# 名称后缀
# nameSuffix: -v1

Overlay环境配置

overlays/production/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 引用base
namespace: production
bases:
  - ../../base

# 副本数覆盖
replicas:
  - name: my-app
    count: 10

# 镜像覆盖
images:
  - name: my-app
    newName: harbor.example.com/prod/my-app
    newTag: v1.2.3

# ConfigMap生成器
configMapGenerator:
  - name: my-app-config
    behavior: replace
    files:
      - application.yml=application-production.yml

# Secret生成器
secretGenerator:
  - name: my-app-secret
    behavior: create
    envs:
      - .env.production

# 资源补丁
patchesStrategicMerge:
  - deployment-resources.yaml
  - deployment-probes.yaml
  - pvc.yaml

# 命名空间
namespace: production

# 通用标签覆盖
commonLabels:
  environment: production
  tier: backend

# 通用注解覆盖
commonAnnotations:
  env: production
  prometheus.io/scrape: "true"
  prometheus.io/port: "8080"

overlays/production/deployment-resources.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      containers:
        - name: my-app
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              cpu: 2000m
              memory: 4Gi

overlays/production/pvc.yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-logs
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: fast-ssd
  resources:
    requests:
      storage: 50Gi

overlays/production/application-production.yml

server:
  port: 8080

spring:
  application:
    name: my-app
  datasource:
    url: jdbc:mysql://mysql-prod.svc:3306/mydb
    username: prod_user
    password: ${DB_PASSWORD}

logging:
  level:
    root: INFO
    com.example: DEBUG
  file:
    path: /logs

overlays/production/.env.production

1
2
3

DB_PASSWORD=prod_secure_password_123
API_KEY=prod_api_key_xyz
REDIS_PASSWORD=prod_redis_pass

部署命令

# 构建配置（不应用，查看最终YAML）
kubectl kustomize overlays/production

# 保存渲染结果
kubectl kustomize overlays/production > rendered-prod.yaml

# 查看差异
kubectl diff -k overlays/production

# 直接应用
kubectl apply -k overlays/production

# 删除资源
kubectl delete -k overlays/production

# 查看资源
kubectl get all -l app.kubernetes.io/name=my-app -n production

统一部署管理配置

1. Namespace管理

方式一：在Overlay中指定

1
2

# overlays/production/kustomization.yaml
namespace: production

方式二：作为资源管理

# overlays/production/kustomization.yaml
resources:
  - ../../base
  - namespace.yaml

# overlays/production/namespace.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: production
  labels:
    environment: production
    name: production

2. Secret管理

方案一：环境变量文件

# overlays/production/kustomization.yaml
secretGenerator:
  - name: my-app-secret
    type: Opaque
    envs:
      - .env.production

方案二：字面值

secretGenerator:
  - name: my-app-secret
    type: Opaque
    literals:
      - DB_PASSWORD=prod123
      - API_KEY=xyz789

方案三：命令生成

secretGenerator:
  - name: tls-cert
    type: kubernetes.io/tls
    files:
      - tls.crt=tls.crt
      - tls.key=tls.key

方案四：从现有Secret引用

# overlays/production/kustomization.yaml
generatorOptions:
  disableNameSuffixHash: true

resources:
  - secret.yaml

# overlays/production/secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: my-app-secret
type: Opaque
stringData:
  DB_PASSWORD: prod123

方案五：Sealed Secrets（推荐生产使用）

# 本地生成sealed secret
kubeseal -f secret.yaml -w sealed-secret.yaml

# 在kustomization中引用
resources:
  - sealed-secret.yaml

3. PVC管理

# overlays/production/kustomization.yaml
resources:
  - ../../base
  - pvc-logs.yaml
  - pvc-data.yaml

# overlays/production/pvc-logs.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-logs
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: fast-ssd  # 使用SSD存储类
  resources:
    requests:
      storage: 50Gi

# overlays/production/pvc-data.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-app-data
spec:
  accessModes:
    - ReadWriteMany  # 多节点共享
  storageClassName: nfs-storage
  resources:
    requests:
      storage: 100Gi

4. 镜像版本管理

方式一：直接指定

images:
  - name: my-app
    newName: harbor.example.com/prod/my-app
    newTag: v1.2.3

方式二：使用SHA256

images:
  - name: my-app
    newName: harbor.example.com/prod/my-app
    digest: sha256:abc123def456...  # 最安全的方式

方式三：多个镜像

images:
  - name: nginx
    newName: harbor.example.com/library/nginx
    newTag: 1.21-alpine
  - name: redis
    newName: harbor.example.com/library/redis
    newTag: 6.2-alpine
  - name: my-app
    newName: harbor.example.com/prod/my-app
    newTag: v1.2.3

方式四：CI/CD动态更新

# 在CI Pipeline中
export IMAGE_TAG=$(git rev-parse --short HEAD)
cd overlays/production
kustomize edit set image my-app=harbor.example.com/prod/my-app:$IMAGE_TAG
kubectl apply -k .

5. 节点亲和性配置

# overlays/production/deployment-affinity.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      affinity:
        # 节点亲和性
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: node.kubernetes.io/instance-type
                    operator: In
                    values:
                      - c5.2xlarge
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              preference:
                matchExpressions:
                  - key: topology.kubernetes.io/zone
                    operator: In
                    values:
                      - us-west-1a
        # Pod亲和性
        podAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values:
                        - mysql
                topologyKey: kubernetes.io/hostname

在kustomization中引用：

1
2

patchesStrategicMerge:
  - deployment-affinity.yaml

6. 污点和容忍配置

# overlays/production/deployment-taints.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      # 容忍专用节点污点
      tolerations:
        - key: workload
          operator: Equal
          value: dedicated
          effect: NoSchedule
        - key: node.kubernetes.io/not-ready
          operator: Exists
          effect: NoExecute
          tolerationSeconds: 300
        # 容许GPU节点
        - key: nvidia.com/gpu
          operator: Exists
          effect: NoSchedule

7. 副本数量管理

# 方式一：replicas字段（推荐）
replicas:
  - name: my-app
    count: 10
  - name: my-app-sidecar
    count: 2

# 方式二：Patch方式
# overlays/production/deployment-replica.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 10

8. ConfigMap管理

# 方式一：configMapGenerator（推荐）
configMapGenerator:
  # 从文件生成
  - name: my-app-config
    behavior: replace
    files:
      - application.yml=application-production.yml
      - logback.xml=logback-production.xml

  # 从字面值生成
  - name: my-app-env
    behavior: create
    literals:
      - SPRING_PROFILES_ACTIVE=production
      - LOG_LEVEL=INFO
      - JAVA_OPTS=-Xms2g -Xmx4g

  # 从env文件生成
  - name: my-app-file-env
    behavior: create
    envs:
      - .env.production

# 方式二：直接引用资源
resources:
  - configmap.yaml

完整生产环境示例

overlays/production/kustomization.yaml

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

# 命名空间
namespace: production

# 引用base
bases:
  - ../../base

# 额外资源
resources:
  - namespace.yaml
  - pvc-logs.yaml
  - pvc-data.yaml
  - hpa.yaml
  - service-monitor.yaml
  - network-policy.yaml

# 副本数
replicas:
  - name: my-app
    count: 10

# 镜像版本
images:
  - name: my-app
    newName: harbor.example.com/prod/my-app
    newTag: v1.2.3

# ConfigMap
configMapGenerator:
  - name: my-app-config
    behavior: replace
    files:
      - application.yml=config/application-production.yml
  - name: my-app-env
    behavior: merge
    literals:
      - ENV=production
      - LOG_LEVEL=INFO

# Secret
secretGenerator:
  - name: my-app-secret
    behavior: create
    envs:
      - .env.production

# Patch
patchesStrategicMerge:
  - deployment-resources.yaml
  - deployment-affinity.yaml
  - deployment-taints.yaml
  - deployment-probes.yaml

# 通用标签
commonLabels:
  environment: production
  tier: backend
  team: platform

# 通用注解
commonAnnotations:
  env: production
  prometheus.io/scrape: "true"
  prometheus.io/port: "8080"

CI/CD集成

GitLab CI示例

# .gitlab-ci.yml
stages:
  - build
  - deploy

variables:
  REGISTRY: harbor.example.com
  APP_NAME: my-app

build:
  stage: build
  image: docker:24
  services:
    - docker:24-dind
  script:
    - docker build -t $REGISTRY/$APP_NAME:$CI_COMMIT_SHA .
    - docker push $REGISTRY/$APP_NAME:$CI_COMMIT_SHA
  only:
    - main
    - develop

deploy:dev:
  stage: deploy
  image: bitnami/kubectl:latest
  environment:
    name: dev
  script:
    - cd overlays/dev
    - kustomize edit set image $REGISTRY/$APP_NAME=$REGISTRY/$APP_NAME:$CI_COMMIT_SHA
    - kubectl apply -k .
    - kubectl rollout status deployment/my-app -n dev
  only:
    - develop

deploy:prod:
  stage: deploy
  image: bitnami/kubectl:latest
  environment:
    name: production
  script:
    - cd overlays/production
    - kustomize edit set image $REGISTRY/$APP_NAME=$REGISTRY/$APP_NAME:$CI_COMMIT_SHA
    - kubectl apply -k .
    - kubectl rollout status deployment/my-app -n production
  when: manual
  only:
    - main

ArgoCD集成

# argocd/application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app-production
  namespace: argocd
spec:
  project: production
  source:
    repoURL: https://github.com/example/k8s-manifests.git
    targetRevision: main
    path: overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true

总结

Kustomize最佳实践

目录结构规范
- base存放通用配置
- overlays管理环境差异
- 清晰的命名约定
版本管理
- 使用Git管理所有配置
- 镜像使用SHA256或明确的tag
- 不要使用latest
Secret管理
- 生产环境使用Sealed Secrets
- 不要将敏感信息提交到Git
- 使用External Secrets Operator集成Vault
组件复用
- 抽取通用配置为组件
- 建立Kustomize组件库
- 避免重复配置
CI/CD集成
- 自动化镜像tag更新
- 使用kubectl diff预览变更
- 配置验证通过后再应用

Kustomize vs Helm选择

场景	推荐方案	原因
微服务配置管理	Kustomize	灵活性高，Git友好
第三方应用部署	Helm	生态丰富，一键部署
复杂模板需求	Helm	Go Template功能强大
简单配置	Kustomize	无需学习模板
GitOps	Kustomize	天然支持

学习路径

基础语法：base + overlay结构
Patch策略：StrategicMerge vs JSON6902
组件复用：提取通用配置
CI/CD集成：自动化部署流程
GitOps实践：与ArgoCD/Flux结合

Kustomize是云原生时代配置管理的理想工具，掌握它能显著提升Kubernetes应用管理效率，在实际部署场景下，对于新项目不同环境差异化很小，可以结合VibeCoding工具生成一键部署脚本，快速交付新环境。

企业级私有云平台深度对比：ZStack vs TStack

wzdushu@gmail.com (wanzi) — Sat, 14 Jun 2025 11:00:00 +0800

ZStack 与 TStack (腾讯云专有云) 选型对比

由于金融客户特殊性要求，需要在私有化交付过程中，进行三方私有云平台选型，本次主要针对Zstack和Tstack进行对比:

在私有云/混合云市场中，ZStack（云轴科技,背后为阿里云）与 TStack（腾讯云专有全栈云解决方案，现多整合进 TCE/TCS 体系）是两类典型代表。前者以“产品化、轻量级、独立厂商”著称，后者以“全栈能力、公有云同源、大厂生态”为核心。

1. 核心定位与背景

维度	ZStack (云轴科技)	TStack / TCE (腾讯云)
厂商性质	独立软件厂商 (ISV)专注于云平台软件研发，中立性强。	公有云厂商 (CSP)腾讯内部技术输出，强依赖腾讯生态。
核心定位	产品化私有云/超融合强调“简单、健壮、弹性、智能”(4S)，主打 VMware 替代及中小规模私有云。	全栈私有云/行业云强调“公有云体验私有化”，提供 IaaS+PaaS+SaaS 全栈能力，主打大型政企数字化转型。
技术基因	自研架构 (非 OpenStack 魔改)，代码自主率高，轻量级。	源于腾讯公有云 (Tencent Cloud)，基于 OpenStack/K8s 深度定制，重平台化。
典型客户	中小企业、医院、学校、部分国企、边缘计算场景。	大型央企、政府委办局、金融机构、需要复杂 PaaS 能力的集团。

2. 架构与技术特性对比

2.1 架构设计

ZStack:
- 微服务架构：所有组件进程化，无外部依赖（如无需单独部署 MySQL、RabbitMQ），一键安装，30分钟即可完成部署。
- 无状态设计：管理节点支持高可用 (HA)，故障自动切换。
- 升级平滑：支持无缝在线升级，不中断业务。
TStack (TCE):
- 复杂分布式架构：依赖大量中间件组件，部署通常需要专业团队介入，周期较长（天/周级别）。
- 公有云同源：底层技术与腾讯公有云高度一致，适合需要“混合云一致性”的场景。
- 模块化交付：可按需选择企业版、大数据版、AI版等，但集成度高导致耦合度也相对较高。

2.2 虚拟化与容器

功能	ZStack	TStack (TCE)
虚拟化内核	基于 KVM 深度优化，自研管理引擎，性能损耗极低。	基于 KVM，继承腾讯公有云神龙架构部分特性，性能强劲。
容器支持	ZStack Zaku：提供容器引擎，支持虚拟机与容器统一管理，轻量级 K8s。	TCS (Tencent Cloud-native Suite)：企业级 K8s 平台，功能极其丰富，支持复杂的微服务治理、DevOps。
存算分离	支持 ZStack Cube 超融合架构，内置分布式存储。	支持 CBS/CFS 等腾讯自研存储对接，也可对接第三方存储。

3. 信创与生态兼容性

随着国产化要求的深入，信创能力成为选型的关键一票。

ZStack:
- 全栈信创：宣称“一云八芯”，全面支持飞腾、鲲鹏、海光、龙芯、兆芯、申威等国产芯片。
- 生态适配：已适配 140+ 国产软硬件产品（操作系统、数据库、中间件）。
- 优势：作为独立厂商，对国产小众芯片和操作系统的适配响应速度极快，灵活性高。
TStack (TCE):
- 主流信创：重点支持鲲鹏、飞腾等主流国产芯片（尤其是与腾讯有战略合作的厂商）。
- 生态绑定：深度整合腾讯云生态（如 TDSQL 数据库、TDW 大数据），在腾讯系信创方案中表现优异。
- 优势：在金融、政务等大型信创项目中，能提供从芯片到应用的全链路兜底服务。

4. 运维与交付体验

维度	ZStack	TStack (TCE)
部署难度	⭐ (极简)单节点即可启动，Web 界面引导式安装，自动化程度极高。	⭐⭐⭐ (复杂)通常需要原厂或认证合作伙伴现场部署，依赖复杂的预检查和环境准备。
日常运维	⭐⭐ (简单)界面直观，功能聚焦，普通运维人员上手快。	⭐⭐⭐ (专业)功能极其丰富但复杂，需要专门培训的运维团队，学习曲线陡峭。
升级维护	支持在线无缝升级，版本迭代快。	升级流程严谨但繁琐，通常涉及停机窗口或复杂的灰度发布策略。
售后服务	原厂直服 + 合作伙伴，响应灵活。	依托腾讯云庞大的服务体系，三线支持机制完善，但流程相对标准化（有时略显僵化）。

5. 成本分析 (TCO)

ZStack:
- 授权模式：通常按 CPU 插槽或节点数授权，价格透明。
- 硬件要求：对硬件配置要求相对较低，利旧能力强，可使用通用 x86 服务器。
- 人力成本：由于运维简单，可大幅降低对高级运维专家的依赖。
- 总体评价：初期投入低，长期持有成本低，适合预算敏感型项目。
TStack (TCE):
- 授权模式：整体解决方案打包，包含软件授权、实施费、维保服务费，价格较高。
- 硬件要求：推荐专用硬件或高性能服务器，对网络架构要求高（往往需要万兆网络起步）。
- 人力成本：需要专职云管团队，培训成本高。
- 总体评价：初期投入高，适合预算充足、追求极致稳定性和全栈能力的大型项目。

6. 选型决策矩阵

请根据您的实际场景对照下表：

场景特征	推荐方案	理由
VMware 替代	ZStack	ZStack 专为替代 VMware 设计，迁移工具成熟，成本低，架构轻量，风险小。
中小型私有云 (<50 节点)	ZStack	部署快，运维少，性价比高，功能完全够用。
大型政企/金融核心云 (>100 节点)	TStack (TCE)	需要极高的稳定性、复杂的 PaaS 能力、以及大厂的品牌背书和兜底服务。
需要深度 PaaS/大数据/AI 能力	TStack (TCE)	腾讯在大数据、AI、微信生态整合上有天然优势，TCE 能直接复用公有云能力。
信创环境复杂 (多种国产芯片混用)	ZStack	独立厂商对异构芯片的兼容性和适配响应速度通常优于大厂标准品。
混合云架构 (与公有云联动)	TStack (TCE)	如果未来计划重度使用腾讯公有云，TCE 能实现真正的“一朵云”体验。
预算有限 / 快速上线	ZStack	开箱即用，几天内即可投产，显著降低 TCO。

7. 总结与建议

选择 ZStack，如果：
- 您希望快速构建私有云，厌倦了复杂的 OpenStack 部署。
- 您的主要目标是替代 VMware，降低授权成本。
- 您的团队规模较小，缺乏专门的云运维专家。
- 您需要高度的自主可控和中立的第三方软件供应商。
选择 TStack (TCE)，如果：
- 您是大型集团、央企或金融机构，对稳定性有近乎苛刻的要求。
- 您需要全栈能力（不仅仅是虚拟机，还包括大数据、AI、微服务治理等 PaaS 服务）。
- 您的战略方向是混合云，且倾向于使用腾讯公有云作为公有侧。
- 您有足够的预算组建专业的云管团队，并购买原厂高级服务。

💡 最终建议：

在当下的市场环境下，“小而美”与“大而全”并存。对于 80% 的通用型企业场景，ZStack 往往是更务实、更高效的选择；而对于那 20% 关乎国计民生、业务极度复杂的核心场景，TStack (TCE) 的大厂底蕴则不可或缺。建议在选型前进行 POC 测试，重点验证部署效率、信创兼容性及实际业务负载下的性能表现。

其实在私有化部署场景中，zstack和stack已经涵盖了，IAAS层虚拟机和分布式存储、PaaS容器层，唯一缺少的是RDS平台，因此对于配合这两个平台，在增配三方RDS平台的时候也需要注意适配度，一般Zstack配套沃趣，Tstack配套爱可生；

在使用了沃趣和爱可生两家后，建议使用沃趣平台，主要原因为平台功能、高可用、UI易用这三点做的比较好一些, 支持Mysql、Oracle、SQL Server、PostgreSQL、Redis、MongoDB、OceanBase、TiDB、ES、RabbitMQ、Kafka、RocketMQ等.

Azure云AKS集群调用Blob几种方式

wzdushu@gmail.com (wanzi) — Fri, 30 May 2025 21:22:42 +0800

在使用Azure云过程中，经常会用到Blob存储，这里记录一下，再业务使用过程中常用的几种场景：

一、通过Microsoft Entra ID应用程序账户访问Blob

优点：

可用于非 Azure 环境（如本地服务器、AWS EC2）
支持跨订阅、跨租户访问

缺点：

密钥必须安全存储（如 Key Vault）
密钥到期需手动轮换，否则应用中断
存在凭据泄露风险（尤其在 CI/CD 中硬编码）

具体配置如下：

1、配置应用程序专用账户

在Entra ID中注册应用，创建服务主体，生成客户端密钥或证书，将应用分配到Storage Blob Data Contributor角色(读写)，同时记录如下信息：

Tenant ID（租户 ID）
Client ID（客户端 ID）
客户端密钥（Client secrets），有过期时间，到期后需要手动更新。

2、赋予账户Azure Blob存储权限

(1)在Azure门户，转到存储账户（StorageAccount），选择你的存储账户（mdblob001）；

(2)在左侧菜单，选择访问控制（IAM）（Access Control），点击 + 添加（Add）→添加角色分配（Add role assignment）；选择角色：Storage Blob Data Contributor（允许读取 & 写入 Blob）；

(3)分配访问权限给：用户、组或服务主体（User, group, or service principal），选择成员：搜索你的应用名称（MyBlobApp），点击选择（Select），点击下一步 → 分配。

3、客户端调用Blob

应用代码中使用ClientSecretCredential或ClientCertificateCredential获取令牌访问Blob，这里拿Python SDK举例：

需要提前安装:

`1`	`pip install azure-identity azure-storage-blob`

from azure.identity import ClientSecretCredential
from azure.storage.blob import BlobServiceClient

# 配置 Entra ID 应用信息
TENANT_ID = "3c4e99f3-4831-4352-ae86-4d8f59512865"
CLIENT_ID = "3357a2b1-9895-484d-8754-42c162f2c9eb"      # 应用程序（客户端）ID
CLIENT_SECRET = "DoB8Q~4Gwl6sdzV_ocfUvXA3BtHYJLgrimwwMcj1"

# 存储账户和本地文件
ACCOUNT_NAME = "mdblob001"
LOCAL_FILE_PATH = "/mnt/d/file.txt"
BLOB_NAME = "uploaded-file.txt"          # 上传后在 Blob 中的名称

# 获取 Token 凭据
credential = ClientSecretCredential(
    tenant_id=TENANT_ID,
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET
)

# 创建 Blob 客户端
blob_service_client = BlobServiceClient(
    account_url=f"https://{ACCOUNT_NAME}.blob.core.windows.net",
    credential=credential
)

# 列出容器（测试权限）
try:
    containers = blob_service_client.list_containers()
    for container in containers:
        print("Container:", container.name)
except Exception as e:
    print("Error:", e)

# === 上传文件 ===
try:
    blob_client = blob_service_client.get_blob_client(
        container=CONTAINER_NAME,
        blob=BLOB_NAME
    )

    with open(LOCAL_FILE_PATH, "rb") as data:
        blob_client.upload_blob(data, overwrite=True)  # overwrite=True 允许覆盖

    print(f"✅ 文件 '{LOCAL_FILE_PATH}' 已成功上传为 '{BLOB_NAME}'")

except FileNotFoundError:
    print("❌ 本地文件未找到")
except Exception as e:
    print("❌ 上传失败:", e)

二、通过AKS-系统托管标识访问Blob

系统托管标识（System-assigned Managed Identity）是Azure 提供的一种自动管理的服务主体（Service Principal），可为支持的 Azure 资源（如 VM、AKS、App Service 等）提供安全的身份认证能力，AKS默认已经启用。

优点：

自动管理生命周期，随着AKS集群创建、销毁等
无需管理凭证，完全无秘钥访问
更高安全，凭据不会暴露在代码、配置文件或环境变量中
可以和Azure的RBAC深度集成
开发SDK只需配置DefaultAzureCredential即可自动获取令牌

缺点:

不能跨资源复用，比如如多个workload使用不同权限，无法细化
标识自动管理，但是RBAC需要手动配置
无法跨云进行标记
无法自定义命名

1、AKS集群启用系统分配的托管标识：

az aks create --resource-group test --name md-test-southafrica --generate-ssh-keys #仅针对新集群启动系统托管标识
az aks update --resource-group test --name md-test-southafrica --enable-managed-identity # 针对已经存在集群
az aks show --resource-group test -n md-test-southafrica --query "identity" # 查看系统托管标识
{
"delegatedResources": null,
"principalId": "37e6bf32-b18d-4e3a-9f97-b86d0c9dc2cf",
"tenantId": "3c4e99f3-4831-4352-ae86-4d8f59512865",
"type": "SystemAssigned",
"userAssignedIdentities": null
}

2、为托管标识分配 Blob Storage 角色

可选角色：

Storage Blob Data Reader：只读
Storage Blob Data Contributor：读写
Storage Blob Data Owner：读写 + ACL 管理（用于 ADLS Gen2）

使用 Azure CLI 为该标识授予对 Blob Storage 的访问权限（例如 Storage Blob Data Contributor）：

# 获取存储账户 ID
STORAGE_ACCOUNT_ID=$(az storage account show -n mdblob001 -g test --query id -o tsv)
echo $STORAGE_ACCOUNT_ID
/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001
# 分配角色
AKS_PRINCIPAL_ID=$(az aks show --resource-group test --name md-test-southafrica --query "identity.principalId" --output tsv)
echo "AKS Principal ID: $AKS_PRINCIPAL_ID"
AKS Principal ID: 37e6bf32-b18d-4e3a-9f97-b86d0c9dc2cf
az role assignment create --assignee "37e6bf32-b18d-4e3a-9f97-b86d0c9dc2cf" --role "Storage Blob Data Contributor" --scope "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001" # 授权给AKS系统托管认证

{
"condition": null,
"conditionVersion": null,
"createdBy": "dc8278a7-78d6-4f6e-971c-8974d0ac4e2f",
"createdOn": "2025-02-19T04:31:42.582306+00:00",
"delegatedManagedIdentityResourceId": null,
"description": null,
"id": "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001/providers/Microsoft.Authorization/roleAssignments/81f9e7d1-b83c-4c4b-aab0-047fc4fb525f",
"name": "81f9e7d1-b83c-4c4b-aab0-047fc4fb525f",
"principalId": "37e6bf32-b18d-4e3a-9f97-b86d0c9dc2cf",
"principalName": "ad674b19-a3b1-47ed-9463-128289ae5e34",
"principalType": "ServicePrincipal",
"resourceGroup": "Test",
"roleDefinitionId": "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/providers/Microsoft.Authorization/roleDefinitions/ba92f5b4-2d11-453d-a403-e96b0029c9fe",
"roleDefinitionName": "Storage Blob Data Contributor",
"scope": "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001",
"type": "Microsoft.Authorization/roleAssignments",
"updatedBy": "dc8278a7-78d6-4f6e-971c-8974d0ac4e2f",
"updatedOn": "2025-02-19T04:31:42.582306+00:00"
}
az role assignment list --scope "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001" --output table #列出存储账户下授权信息
Principal                             Role                           Scope
--------------------------------------------------------------------------------
ad674b19-a3b1-47ed-9463-128289ae5e34  Storage Blob Data Contributor  /subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001

3、验证

使用python SDK构建容器，验证访问：

from azure.storage.blob import BlobServiceClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
blob_service_client = BlobServiceClient(
    account_url="https://mdblob001.blob.core.windows.net",
    credential=credential
)

# 列出容器
containers = blob_service_client.list_containers()
for c in containers:
    print(c.name)

DefaultAzureCredential 会自动尝试多种身份验证方式，在 AKS 中会通过 IMDS（Instance Metadata Service）获取令牌，前提是 Pod 运行在启用了托管标识的节点上。

三、通过AKS-用户托管标识访问Blob

1、创建用户分配的托管标识：

az group create -n rg-aks-wi -l test # 创建资源组,已经已经存在请忽略
az identity create --name MD-Blob-Identity --resource-group test # 创建用户分配托管标识
{
  "clientId": "7d9b65f6-959d-4a74-ab3f-67d16adc8c37",
  "id": "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourcegroups/test/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MD-Blob-Identity",
  "location": "southafricanorth",
  "name": "MD-Blob-Identity",
  "principalId": "bdd58864-063f-451d-b352-2dded3582b36",
  "resourceGroup": "test",
  "systemData": null,
  "tags": {},
  "tenantId": "3c4e99f3-4831-4352-ae86-4d8f59512865",
  "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
}
# 获取关键信息
export USER_ASSIGNED_CLIENT_ID="$(az identity show -g test -n MD-Blob-Identity --query clientId -o tsv)" 
export USER_ASSIGNED_PRINCIPAL_ID="$(az identity show -g test -n MD-Blob-Identity --query principalId -o tsv)"

2、为标识分配Blob Storage权限

STORAGE_ACCOUNT_ID=$(az storage account show -n mdblob001 -g test --query id -o tsv)
echo $STORAGE_ACCOUNT_ID
/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourceGroups/Test/providers/Microsoft.Storage/storageAccounts/mdblob001
az role assignment create \
  --role "Storage Blob Data Contributor" \
  --assignee $USER_ASSIGNED_PRINCIPAL_ID \
  --scope $STORAGE_ACCOUNT_ID

3、在 AKS 上启用 Workload Identity（如未启用）

Workload Identity基于OIDC，标准、安全、微软主推一种方式

# 启用 OIDC issuer（AKS 1.24+ 支持）
az aks update -g test -n md-test-southafrica --enable-oidc-issuer
# 获取 OIDC issuer URL
export AKS_OIDC_ISSUER=$(az aks show -g test -n md-test-southafrica --query "oidcIssuerProfile.issuerUrl" -o tsv)
echo $AKS_OIDC_ISSUER

4、将用户标识与 Kubernetes Service Account 联邦（Federate）

# 获取用户标识的 clientId
export USER_ASSIGNED_CLIENT_ID=$(az identity show -g test -n MD-Blob-Identity --query clientId -o tsv)
# 创建联邦凭据（允许 AKS 中的特定 ServiceAccount 使用此标识）
az identity federated-credential list --resource-group test --name md-test-southafrica
az identity federated-credential create --name my-fed-cred  \
--identity-name MD-Blob-Identity \
--resource-group test \
--issuer $AKS_OIDC_ISSUER  \
--subject system:serviceaccount:demo:md-blob-sa
--audience api://AzureADTokenExchange
{
"audiences": [
"api://AzureADTokenExchange"
],
"id": "/subscriptions/cdab1cd0-0556-41bc-8905-33ce907e818a/resourcegroups/test/providers/Microsoft.ManagedIdentity/userAssignedIdentities/MD-Blob-Identity/federatedIdentityCredentials/my-fed-cred",
"issuer": "https://oidc.prod-aks.azure.com/3c4e99f3-4831-4352-ae86-4d8f59512865/",
"name": "my-fed-cred",
"resourceGroup": "test",
"subject": "system:serviceaccount:demo:md-blob-sa",
"systemData": null,
"type": "Microsoft.ManagedIdentity/userAssignedIdentities/federatedIdentityCredentials"
}

subject 格式：system:serviceaccount::

5、在 Kubernetes 中创建 ServiceAccount 并部署应用

创建 ServiceAccount

# blob-sa.yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: blob-access-sa
  namespace: demo
  annotations:
    azure.workload.identity/client-id: "${USER_ASSIGNED_CLIENT_ID}"

kubectl aply -f blob-sa.yaml

6、部署应用

这里以python为例：

# python-blob.yaml 
apiVersion: v1
kind: Pod
metadata:
  name: blob-client
  namespace: demo
  labels:
    azure.workload.identity/use: "true"  # 必须添加此标签！
spec:
  serviceAccountName: blob-access-sa
  containers:
    - name: app
      image: python:3.11-slim
      command: ["sh", "-c"]
      args:
        - |
          pip install azure-identity azure-storage-blob && \
          python -c "
from azure.storage.blob import BlobServiceClient
from azure.identity import DefaultAzureCredential
import os

account = 'mdblob001'
url = f'https://mdblob001.blob.core.windows.net'
client = BlobServiceClient(account_url=url, credential=DefaultAzureCredential())
print('Containers:', [c.name for c in client.list_containers()])
"
      env:
        - name: AZURE_CLIENT_ID
          value: "${USER_ASSIGNED_CLIENT_ID}"  # 可选，但推荐显式指定
  restartPolicy: Never

部署应用

kubectl apply -f python-blob.yaml 
kubectl logs blob-client # 可以正常列出blob里容器，应用使用令牌访问 Blob Storage已经全程无密钥！

至此,Azure云下，三种访问Blob存储的方式实践完成。

Headscale自建企业级VPN网络

wzdushu@gmail.com (wanzi) — Sat, 11 Jan 2025 10:00:00 +0800

项目背景

业务痛点

随着业务增长，目前海外拥有十几个独立的私有网络环境（ZStack/TStack），例如：

海外私有网络A区域
海外私有网络B区域
海外私有网络C区域

每个网络都是独立个体，需要使用不同的VPN客户端拨号才能访问对应网络的资源，这给日常运维管理带来巨大挑战：

运维人员需要在多个VPN客户端间频繁切换
缺乏统一的权限管理和访问控制
网络配置复杂，故障排查困难
无法实现跨网络的自动化运维

解决方案

采用Headscale（服务端）+ Tailscale（客户端）的架构，构建企业级零信任VPN网络：

在阿里云新加坡节点部署Headscale控制服务器
各私有网络节点安装Tailscale客户端并注册到Headscale
实现一次连接，访问所有私有网络资源
支持ACL访问控制、SSO单点登录
Tailscale的多端支持很好，IOS、MacOS 、安卓、win、Linux,同时支持IPv6

Headscale架构介绍

核心组件

Headscale是Tailscale控制服务器的开源实现，完全兼容Tailscale协议：

控制服务器（Headscale）：管理节点注册、密钥分发、地址分配、ACL策略
DERP服务器：中继服务器，用于NAT穿透失败时的流量转发
客户端（Tailscale）：部署在各节点，基于WireGuard建立加密隧道

技术优势

相比传统VPN方案：

零信任架构：默认拒绝所有访问，通过ACL显式授权
NAT穿透：支持STUN协议自动打洞，无需公网IP
Mesh网络：节点间直接通信，无需经过中心服务器
自动重连：网络变化时自动重新建立连接
跨平台支持：Linux/Windows/macOS/BSD/iOS/Android/FreeBSD

Headscale服务端部署

环境准备

# 系统要求
# Ubuntu 20.04+ / CentOS 8+ / Debian 11+
# 公网IP服务器（推荐阿里云新加坡）
# 开放UDP端口：3478（DERP）、41641（Headscale）

# 安装Headscale
wget https://github.com/juanfont/headscale/releases/download/v0.23.0/headscale_0.23.0_linux_amd64.deb
sudo dpkg -i headscale_0.23.0_linux_amd64.deb

# 或使用yum安装（RHEL/CentOS）
sudo yum install -y https://github.com/juanfont/headscale/releases/download/v0.23.0/headscale_0.23.0_linux_amd64.rpm

配置文件

参考: https://github.com/juanfont/headscale/blob/main/config-example.yaml

创建配置文件 /etc/headscale/config.yaml：

# 服务器地址
server_url: https://headscale.wnote.com:443

# 监听地址
listen_addr: 0.0.0.0:8080

# 私钥（自动生成或指定）
private_key_path: /var/lib/headscale/private.key

# DERP中继服务器配置 
derp:
  # 启用嵌入式 DERP 服务器
  server:
    enabled: false
    region_id: 999                     # 使用一个未占用的 ID，避免冲突
    region_code: "self-derp"           # 简短标识
    region_name: "自建合设 DERP"        # 描述名称
    stun_listen_addr: "0.0.0.0:3478"   # STUN 服务监听，必须开放 UDP 3478
    # 【重要】填写你服务器的真实公网 IPv4 地址
    ipv4: "你的服务器公网IP"
    # 如果有公网 IPv6 也可填上
    # ipv6: "你的服务器公网IPv6"
    # 自动将本区域加入 DERP 地图
    automatically_add_embedded_derp_region: true
    # 【安全】强烈建议开启，仅允许你的 Tailnet 客户端使用该中继
    verify_clients: true

  # 你可以选择保留官方 DERP 作为备份，或完全禁用（清空 urls）
  urls:
    - https://controlplane.tailscale.com/derpmap/default   # 保留备份（推荐）
  # 如果你有额外的自建 DERP 节点（如新加坡节点），可保留 paths
  paths:
    - /etc/headscale/derp.yaml

  auto_update_enabled: true
  update_frequency: 24h

# 数据库（默认SQLite，生产环境推荐PostgreSQL）
database:
  type: sqlite
  sqlite:
    path: /var/lib/headscale/db.sqlite

# ACL策略文件
acl_policy_path: /etc/headscale/acl.yaml

# DNS配置
dns:
  nameservers:
    - 1.1.1.1
    - 8.8.8.8
  magic_dns: true  # 启用MagicDNS（node.namespace.vpn）

# OAuth配置（可选）
# oidc:
#   issuer: "https://your-oidc-provider.com"
#   client_id: "your-client-id"
#   client_secret: "your-client-secret"

# 日志配置
log:
  format: text
  level: info

配置DERP中继服务器

首先，先理解一下DERP概念：

DERP服务器，主要是为了在网络条件恶劣（如对称型NAT、严格防火墙）导致无法直连时，有一个可靠、低延迟的备用中继方案，确保设备间总能连通

直连 (P2P)：Headscale 的终极目标是让客户端通过 STUN 协议“打洞”，建立点对点的直接连接，速度最快
中继 (DERP)：当打洞失败时（例如一方在严格的对称型NAT后），流量就会通过 DERP 服务器进行转发。虽然延迟比直连高，但能保证连接不中断

这里如果想自建DERP并精细控制多个DERP节点，就需要创建配置文件，它用于定义你的私有DERP网络区域和节点信息

自建DERP的好处在于：可以避开官方 DERP 服务器在海外的延迟问题，并将中继流量控制在自己的服务器上，提升安全性和稳定性

我这里暂时用不上，仅举例，创建 /etc/headscale/derp.yaml：

# /etc/headscale/derp.yaml
regions:
  # 第一个自建区域，例如：华东地区
  901:
    regionid: 901
    regioncode: "cn-east"   # 区域代码，简短
    regionname: "华东自建节点" # 区域名称
    nodes:
      - name: 901a
        regionid: 901
        # 这里填你独立DERP服务器的域名
        hostname: derp-shanghai.yourdomain.com
        # 你的DERP服务器端口，通常是443或你自定义的端口
        derpport: 12345
        # STUN端口，通常是3478
        stunport: 3478
        stunonly: false

  # 第二个自建区域，例如：华北地区
  902:
    regionid: 902
    regioncode: "cn-north"
    regionname: "华北自建节点"
    nodes:
      - name: 902a
        regionid: 902
        hostname: derp-beijing.yourdomain.com
        derpport: 443  # 假设这个节点用了标准443端口
        stunport: 3478
        stunonly: false

配置创建后，可以在任意Tailscale客户端上查看DERP地图和连通性

tailscale debug derp-map
tailscale debug derp headscale # 测试与特定DERP服务器的连接性

验证客户端是否真正使用自建中继，你可以通过 tailscale status 查看连接状态，若看到 derp=自建区域代码（如 derp=self-derp），说明流量正在通过你的自建中继。

ACL访问控制策略

创建 /etc/headscale/acl.yaml：

# 用户/组定义
groups:
  group:admin:
    - admin@example.com
  group:devops:
    - devops1@example.com
    - devops2@example.com
  group:developer:
    - dev1@example.com
    - dev2@example.com

# 主机标签定义
hosts:
  sg-cloud: "10.100.0.1/32"
  network-a: "10.100.1.0/24"
  network-b: "10.100.2.0/24"
  network-c: "10.100.3.0/24"

# 访问控制规则
acls:
  # 管理员可访问所有资源
  - action: accept
    src:
      - group:admin
    dst:
      - "*:*"

  # 运维团队可访问所有服务器SSH
  - action: accept
    src:
      - group:devops
    dst:
      - "sg-cloud:22"
      - "network-a:22"
      - "network-b:22"
      - "network-c:22"

  # 开发团队可访问应用端口
  - action: accept
    src:
      - group:developer
    dst:
      - "sg-cloud:80,443,8080"
      - "network-a:3306,6379"
      - "network-b:9200,9300"

  # 默认拒绝其他访问
  - action: reject
    src:
      - "*"
    dst:
      - "*:*"

# 标签路由规则（可选）
tagOwners:
  tag:prod:
    - group:admin
    - group:devops
  tag:database:
    - group:admin

启动服务

# 创建必要目录
sudo mkdir -p /var/lib/headscale

# 启动Headscale
sudo systemctl enable headscale
sudo systemctl start headscale
sudo systemctl status headscale

# 查看日志
sudo journalctl -u headscale -f

配置Nginx反向代理

由于之前我们通过acme申请了泛域名证书，可以直接指定SSL证书路径即可,企业中根据实际场景配置：

server {
    listen 443 ssl http2;
    server_name headscale.wnote.com;

    ssl_certificate /etc/ssl/certs/headscale.crt;
    ssl_certificate_key /etc/ssl/private/headscale.key;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        # 长连接超时设置
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_connect_timeout 300s;
    }
    # DERP 中继路径也需要代理（嵌入式 DERP 通过该路径提供服务）
    location /derp {
        proxy_pass http://127.0.0.1:8080/derp;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_set_header X-Forwarded-Proto $scheme;
    }
}

开放防火墙端口

确保服务器防火墙允许以下流量：

端口	协议	用途	说明
443	TCP	HTTPS（控制面 + DERP 中继）	已通过反向代理开放
3478	UDP	STUN 服务	必须开放 UDP 3478，用于 NAT 穿透探测
如果使用云服务商（如 AWS、阿里云），还需在安全组中添加入站规则。

Tailscale客户端部署

安装Tailscale客户端

在各个私有网络节点安装：

# Debian/Ubuntu
curl -fsSL https://tailscale.com/install.sh | sh

# RHEL/CentOS
curl -fsSL https://tailscale.com/install.sh | sh

# Windows
# 下载安装包：https://tailscale.com/download/windows

# macOS
brew install --cask tailscale

# Android/iOS
# 应用商店搜索"Tailscale"安装

注册节点到Headscale

# 方法一：使用Auth Key（推荐）

# 在服务器端创建Auth Key
sudo headscale apikeys create -e 8760h -o api-key.txt

# 客户端注册（替换YOUR_AUTH_KEY）
sudo tailscale up --login-server=https://headscale.wnote.com \
                  --auth-key=YOUR_AUTH_KEY \
                  --advertise-routes=10.0.0.0/24,192.168.1.0/24 \
                  --advertise-exit-node

# 方法二：通过命令行注册
# 1. 在服务器创建用户
sudo headscale users create user@example.com

# 2. 获取注册命令
sudo headscale namespaces create default

# 3. 客户端执行注册并获取URL
sudo tailscale up --login-server=https://headscale.wnote.com

# 4. 在服务器端批准注册
sudo headscale nodes register -u user@example.com -n <节点名>

子网路由配置

在各私有网络网关节点上配置子网路由：

# 启用IP转发
echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
echo "net.ipv6.conf.all.forwarding=1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# 宣告子网路由（在网关节点执行）
sudo tailscale up --advertise-routes=10.100.1.0/24,10.100.2.0/24

# 在服务器端批准路由
sudo headscale routes list
sudo headscale routes enable -r <路由ID>

# 验证路由
sudo tailscale status
ping 10.100.1.10  # 测试跨网络访问

Exit Node配置(非必需)

配置出口节点，用于通过特定节点访问外网（指定互联网出口网关）：

# 在出口节点启用
sudo tailscale up --advertise-exit-node

# 在服务器端批准
sudo headscale nodes list
sudo headscale nodes edit --exit-node <节点ID> --enable

# 客户端使用出口节点
sudo tailscale up --exit-node=<出口节点IP> --exit-node-allow-lan-access

指定将流量通过 <出口节点IP> 转发，并且允许同时访问本地局域网（LAN）。如果不加–exit-node-allow-lan-access，那么连本地局域网（如打印机、路由器管理页面）也会走出口节点，可能导致无法访问。

管理与维护

常用管理命令

# 列出所有节点
sudo headscale nodes list

# 查看节点详情
sudo headscale nodes get -i <节点ID>

# 删除节点
sudo headscale nodes delete -i <节点ID>

# 重命名节点
sudo headscale nodes rename -i <节点ID> --new-name <新名称>

# 设置节点标签
sudo headscale nodes tag set -i <节点ID> -t "tag:prod,database"

# 查看路由
sudo headscale routes list

# 启用/禁用路由
sudo headscale routes enable -r <路由ID>
sudo headscale routes disable -r <路由ID>

# 查看命名空间
sudo headscale namespaces list

# 创建命名空间
sudo headscale namespaces create <命名空间名称>

# 添加用户
sudo headscale users create user@example.com

# 列出API密钥
sudo headscale apikeys list

监控与告警

# 启用Prometheus指标
# 在config.yaml中添加：
metrics:
  listen_addr: 127.0.0.1:9090

# 访问指标
curl http://localhost:9090/metrics

# Grafana Dashboard
# 导入Headscale官方Dashboard：https://grafana.com/grafana/dashboards/18820

备份与恢复

# 备份数据库
sudo cp /var/lib/headscale/db.sqlite /backup/headscale-$(date +%Y%m%d).sqlite

# 备份配置文件
sudo tar -czf /backup/headscale-config-$(date +%Y%m%d).tar.gz /etc/headscale/

# 恢复
sudo systemctl stop headscale
sudo cp /backup/headscale-xxx.sqlite /var/lib/headscale/db.sqlite
sudo systemctl start headscale

生产环境最佳实践

高可用部署

# 使用PostgreSQL作为数据库后端
database:
  type: postgres
  postgres:
    host: pg-cluster.example.com
    port: 5432
    user: headscale
    password: "your-password"
    database: headscale
    sslmode: require

安全加固

使用mTLS认证

tls:
  letsencrypt:
    email: admin@example.com
    agree_tos: true
    listen_host: ":443"

限制IP访问

ip_prefixes:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16

定期轮换密钥

1
2
3

# 重新生成私钥
sudo rm /var/lib/headscale/private.key
sudo systemctl restart headscale

性能优化

部署多个DERP服务器
- 每个大区域部署一个DERP节点
- 使用CDN加速DERP访问
优化Keep-alive

1
2

# 客户端配置
sudo tailscale up --ping=20s  # 心跳间隔

单点故障风险 如果完全禁用官方 DERP（urls: []），且只有一台自建 DERP 服务器，当该服务器宕机或网络故障时，所有需要中继的客户端将无法通信。对于生产环境，建议至少保留官方DERP作为备份，或部署多个自建DERP节点。
证书要求 嵌入式 DERP 依赖 Headscale 的 HTTPS 服务，因此你的域名 headscale.wnote.com 必须有有效 SSL 证书。

故障排查

常见问题

1. 节点无法注册

# 检查服务器端日志
sudo journalctl -u headscale -n 50

# 检查客户端注册URL是否正确
# 确保防火墙开放8080/443端口

2. 无法访问子网路由

# 检查IP转发是否启用
sysctl net.ipv4.ip_forward

# 检查路由是否批准
sudo headscale routes list

# 抓包分析
sudo tcpdump -i tailscale0 -n host 10.100.x.x

3. DERP连接失败

# 测试DERP连通性
tailscale ping --c 100 <DERP服务器IP>

# 检查DERP服务器状态
curl https://your-derp-server.com/derp/latency-check

4. ACL策略不生效

# 验证ACL语法
sudo headscale acl validate

# 查看生效的ACL
sudo headscale acl get

总结

Headscale+Tailscale方案为企业提供了开箱即用的零信任VPN解决方案：

部署简单：服务端一键安装，客户端自动配置
功能强大：支持ACL、SSO、路由、出口节点
性能优异：基于WireGuard，延迟低、吞吐量高
安全可靠：端到端加密、细粒度权限控制

通过在阿里云新加坡部署Headscale控制服务器，将各私有网络统一接入，实现了：

运维人员一次登录访问所有网络
基于ACL的细粒度访问控制
自动化的网络拓扑管理
可审计的操作日志

该方案已在生产环境稳定运行，节点规模10+，日活跃连接100+，故障率<0.1%。

WireGuard构建企业级VPN网络

wzdushu@gmail.com (wanzi) — Fri, 10 Jan 2025 14:22:42 +0800

WireGuard介绍

WireGuard 是一款现代、快速、简单、安全的虚拟私有网络（VPN）协议，旨在取代如IPsec和OpenVPN等传统VPN技术。比IPsec更快、更简单、更精简、更实用，同时避免大量麻烦。相比OpenVPN性能更高,最初是为Linux内核发布，现在已跨平台（Windows、macOS、BSD、iOS、Android）并可广泛部署，目前正在大力开发中，但它可能已经被视为业内最安全、最易于使用和最简单的 VPN 解决方案

主要应用场景：

远程办公安全接入企业内网，员工在家或出差时需安全访问公司内部系统（如文件服务器、ERP、数据库）
跨国分支机构互联（Site-to-Site），例如欧洲办公室与中国总部之间需稳定通信
云服务器与本地数据中心安全互联，将阿里云/AWS/Azure上的业务系统与本地IDC打通
家庭网络与云服务器之间的安全互联，出差访问家庭NAS文件
IoT设备安全通信，智能摄像头、工业传感器、POS机等设备需将数据安全传回数据中心
容器和微服务网络隔离，容器场景下夸主机通信，比如wg-easy,netmaker工具快速构建Overlay网络

WireGuard 部署

安装WireGuard

WireGuard 自 Linux 5.6 起已合并进主线内核，大多数现代发行版可直接安装用户态工具：

1
2

sudo apt update
sudo apt install wireguard wireguard-tools

注意：若使用 CentOS/RHEL，需先启用 EPEL 或使用 elrepo 内核模块；Windows/macOS 客户端可从 wireguard.com 下载官方 GUI 应用。

生成密钥对

cd /etc/wireguard/
umask 077 # 确保密钥文件权限安全
wg genkey | tee server_private.key | wg pubkey > server_public.key # 生成服务器端密钥
wg genkey | tee server_private.key | wg pubkey > client1_public.key # 客户端A密钥
wg genkey | tee server_private.key | wg pubkey > client2_public.key # 客户端B密钥

WireGuard 配置管理

WireGuard 没有严格的服务端/客户端之分，但通常需要一个具有公网IP的节点作为中继服务器（Hub）。

编辑服务器端(中继)配置文件 /etc/wireguard/wg0.conf：

[Interface]
Address = 10.100.0.1/24
ListenPort = 51820
PrivateKey = wg genkey | tee server_private.key | wg pubkey > server_public.key # 生成服务器端密钥

PostUp = iptables -A FORWARD -i %i -j ACCEPT; iptables -A FORWARD -o %i -j ACCEPT; iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -D FORWARD -i %i -j ACCEPT; iptables -D FORWARD -o %i -j ACCEPT; iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

# 客户端 A
[Peer]
PublicKey = client1_public.key
AllowedIPs = 10.100.0.2/32

# 客户端 B
[Peer]
PublicKey = client2_public.key
AllowedIPs = 10.100.0.3/32

设置开机自启动

sudo systemctl enable wg-quick@wg0
sudo systemctl start wg-quick@wg0
# 查看状态
sudo wg show

配置内核转发与防火墙（CentOS/Ubuntu）：

# 启用 IPv4 转发
echo "net.ipv4.ip_forward=1" >> /etc/sysctl.conf
sysctl -p

# 防火墙开放端口 (非必需，根据实际情况来)
sudo firewall-cmd --permanent --add-port=51820/udp
sudo firewall-cmd --permanent --add-rich-rule='rule family=ipv4 source address=10.100.0.0/24 masquerade'
sudo firewall-cmd --reload
# 若使用 iptables，参考上述 PostUp/PostDown 脚本

WireGuard DashBoard

wg-easy（轻量级 Web UI）

特点：单页应用，Docker 一键部署，支持 QR 码扫码连接、流量监控、在线开关客户端。
适用场景：中小团队（<50 用户），快速搭建远程办公 VPN。
一键部署命令：

docker run -d \
  --name=wg-easy \
  -e WG_HOST=your.domain.com \
  -e WG_PORT=51820 \
  -e WG_DEFAULT_ADDRESS=10.100.0.x \
  -e PASSWORD=your_admin_password \
  -v ～/.wg-easy:/etc/wireguard \
  -p 51821:51821 \
  -p 51820:51820/udp \
  weejewel/wg-easy

注意：wg-easy 默认无用户权限隔离，不适用于多租户或高安全要求场景。

Netmaker(企业级SD-WAN架构）)

特点：
- 支持 Mesh 网络（任意节点互联）、Site-to-Site、Kubernetes 集成；
- 提供 REST API、RBAC 权限控制、ACL 策略、指标监控（Prometheus）；
- 控制平面（netmaker） + 数据平面（netclient）分离，支持动态拓扑。
架构组件：
- Netmaker Server：管理节点、策略、证书；
- Netclient：部署在各终端（服务器/PC/IoT），自动注册并拉取配置；
- MQTT Broker（可选）：用于大规模节点状态同步。
部署方式：支持 Helm Chart（K8s）、Docker Compose、systemd。

推荐用于：跨国分支互联、混合云组网、IoT 设备集群管理等复杂拓扑。

Tailscale / Headscale（Zero Trust 架构）

虽非原生 WireGuard，但底层基于 WireGuard 协议；
提供 SSO（Google/Azure/OIDC）、设备认证、细粒度 ACL；
Headscale 为开源自托管版，适合数据合规要求高的企业。

Tailscale是商业SaaS服务（免费版支持 3 人），Headscale是其开源、自托管的替代品，协议完全兼容。

这里强烈推荐方案，建议服务器端采用开源headscale，客户端采用tailscale.

Github Actions入门实践

wzdushu@gmail.com (wanzi) — Fri, 01 Nov 2024 17:22:42 +0800

Github Action是什么？

GitHub Actions 是一个持续集成和持续交付 (CI/CD) 平台，可让您自动化构建、测试和部署流程。您可以创建工作流程来构建和测试对存储库的每个拉取请求，或将合并的拉取请求部署到生产环境中。

GitHub Actions 不仅仅是 DevOps，它还允许您在存储库中发生其他事件时运行工作流程。例如，您可以运行工作流程，以便在有人在您的存储库中创建新问题时自动添加适当的标签。

GitHub提供 Linux、Windows 和 macOS 虚拟机来运行您的工作流程，或者您可以在自己的数据中心或云基础设施中托管自己的自托管运行器。

CICD工具选型

目前CICD的市场真是百花齐放，除了github actions外还有很多其他CICD工具可供选择，比如：Gitlab CI、Jenkins、专注于云原生的Tekton、Bitbucket Pipelines、AWS CodePipeline、Bitbucket Pipelines、Azure DevOps、阿里云云效等等

而选择那种方式来实现自己业务自动化流水线，就要根据自己的实际情况来选择了，下面推荐从如下几个方面入手：

成本，是选择开源方案还是选择付费商业版本，如果把成本放在第一位，需要考虑搭建开源软件服务器成本和付费软件的授权成本。
易用性和学习路线，主要考虑系统界面是否美观以及技术文档是否完善，界面这方面很难评判，而技术文档可以查看官方文档是否详细以及工作流是采用yaml还是新语言。
可扩展和灵活性，主要考虑系统插件和自定义需求是否能够满足，这方面还要看个人需求，比如有些企业需要CICD和jira打通，那选择Bitbucket Pipelines更好。
集成能力，主要考虑是否和目前代码仓库、测试框架、部署环境集成以及API功能完善程度，比如你的代码仓库在Github上，当然选择github actions更好一些。
安全性，主要考察是否有访问控制、数据加密等安全特性，这个根据自己实际需求来选择。
性能，主要考察大规模部署的性能瓶颈，往往这个需要结合成本或者资源需求来比较，比如你日常构建对文件传输和带宽有很严格需要，用github actions这种就不是最好的选择了。
企业级方案，主要考察高并发、多租户、安全合规等，往往对于企业到一定规模，会有很多定制需求，看工具是否有企业解决方案。
云原生支持，主要考察业务在kubernetes下的支持程度，特别是新版本，这方面Tekton更有优势。
社区和生态，主要考察项目或者产品哪些用户在使用，以及社区活跃度，这方面jenkins、gitlab、github相对更有优势。

Github Actions组件

1. workflow

从字面意思可以看出workflow是一种工作流程，而这里主要为了配置github actions的CICD自动化流程，通常使用yaml文件定义，定义完成以后可以自动触发工作流也可以手动触发工作流程。

workflow的工作目录一般为仓库的下.github/workflow目录下,一个存储库可以有多个工作流，每个工作流可以执行一组不同的任务，这里的任务也就是常说的job任务。例如：

构建和测试拉取请求。
每次发布时部署您的应用程序。
每当打开新问题时添加标签。

当然，工作流之间也可以相互引用。

在实际使用当中，我们通常采用workflow模版来快速编写工作流程，而github也提供了各类场景工作流模版，比如

CI：持续集成工作流
部署：部署工作流
自动化：自动化工作流
代码扫描：代码扫描工作流
github pages：pages工作流

在编写工作流的时候，需要注意常见关键字的意思，下面我简单梳理了一下，方便后面使用：

name: 定义工作流程名称
run-name: 定义工作流运行时名称
on: 定义触发器，可以是一个事件也可以是多个事件或者是根据匹配来触发
env：定义工作流全局变量
jobs: 定义工作流任务
permissions: 定义工作流对仓库权限
default: 定义默认配置,可以用在全局或者某一个job中，比如定义shell或者工作目录等
on.schedule: 定义工作流时间计划
on.workflow_call: 定义不同工作流的输入和输出过程中信息传递。
on.workflow_dispatch：定义特定工作流中，输入一些标记来触发
jobs.<job_id>.name: 定义单个job的任务名称
jobs.<job_id>.runs-on: 选择jobs运行环境，默认为github官方的，也可以选择高性能机器或者托管自己主机
jobs.<job_id>.steps: 定义单个job不同的运行阶段，比如一个job里有checkout代码，也有build
jobs.<job_id>.env：定义单个job特定变量，属于map类型，也可以设置在全局。
jobs.<job_id>.environment: 定义单个Job里引用，内容可以是变量或者上下文的表达式。
jobs.<job_id>.uses: 定义使用那种action，有的时候部署一些复杂场景，需要用到一些开源比较好的action
jobs.<job_id>.with: 指定参数，一般在任务构建的时候，需要指定一个版本
jobs.<job_id>.needs: 一般多个job的时候，处理job之间依赖关系
jobs.<job_id>.if: 指定job运行条件
jobs.<job_id>.container: 指定单个job里指定容器服务，注意对runner的操作系统有要求，比如ubuntu
jobs.<job_id>.outputs: 定义作业输出一些内容

2. 事件触发器

上一步，我们知道了工作流，那如何触发工作流呢？这个时候就需要定义一个事件触发器，比如常用事件触发器方式：

代码仓库变更触发，比如推送到代码默认分支时触发
github之外发生，并触发repository_dispatch事件
预定时间
手动触发

工作流触发器使用on定义，常见几种配置：

设置一个事件的触发器，当推送到工作流存储库中的任何分支时触发：

`1`	`on: push`

设置一个多个事件的触发器，当推送到工作流存储库中的任何分支时触发：

`1`	`on: [push, fork]`

当有多个分支的时候，需要过滤特定分支，比如main或者releases相关分支，有推送即触发：

on:
  push:
    branches:
      - main
      - 'releases/**'

github本身也可以对issues进行匹配来触发

on:
  issues:
    types:
      - opened
      - labeled

3. Jobs

一般工作流中由一个或多个jobs组成，默认情况下并行运行，需要注意：jobs.<job_id>是job的唯一标识符

比如，我们定义一个job名为Docker build，而对于这个job, build才是job的唯一标识符

jobs:
  build:
    name: Docker build
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

另外,job之间也可以定义依赖关系，通过jobs.<job_id>.needs关键字定义，比如:

jobs:
  job1:
  job2:
    needs: job1
  job3:
    needs: [job1, job2]

在此示例中，job1必须在job2开始之前成功完成，并且job3等待job1和job2完成。

4. Actions

Action是Github上自定义应用程序，用于执行复杂但经常重复的任务。使用操作有助于减少您在工作流程文件中编写的重复代码量。

Actions可以从GitHub拉取您的Git仓库，为您的构建环境设置正确的工具链，或设置对您的云提供商的身份验证。

一般通过关键字uses来定义，比如使用官方: actions/checkout@v4

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production

    steps:
    - name: Checkout
      uses: actions/checkout@v4

您可以编写自己的操作，也可以在 GitHub Marketplace 中找到工作流程中使用的操作。

5. Runners

Runners是一种在触发工作流程时运行工作流程的服务器。通过关键字runs-on来定义使用那种类型runners。每个运行器一次可以运行一项作业，这点确实和gitlab CI里的runner很像。

GitHub提供Ubuntu Linux、Microsoft Windows和macOS相关的runner来运行工作流。每个工作流程都运行在在全新、新配置的虚拟机中执行。

当然，如果默认Runners无法满足你的业务需求，比如需要ARM架构虚拟机，将自己服务器托管给github来管理；或者资源无法满足也可以申请更大的runners。

以下示例工作流有两个作业，名为 Run-npm-on-Ubuntu 和 Run-PSScriptAnalyzer-on-Windows。触发此工作流时，GitHub 为每个作业预配新的虚拟机。

名为 Run-npm-on-Ubuntu的作业在Linux VM上执行，因为作业runs-on: 指定 ubuntu-latest。名为 Run-PSScriptAnalyzer-on-Windows的作业在Windows VM 上执行，因为作业runs-on: 指定 windows-latest。

name: Run commands on different operating systems
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  Run-npm-on-Ubuntu:
    name: Run npm on Ubuntu
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '14'
      - run: npm help

  Run-PSScriptAnalyzer-on-Windows:
    name: Run PSScriptAnalyzer on Windows
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install PSScriptAnalyzer module
        shell: pwsh
        run: |
          Set-PSRepository PSGallery -InstallationPolicy Trusted
          Install-Module PSScriptAnalyzer -ErrorAction Stop
      - name: Get list of rules
        shell: pwsh
        run: |
          Get-ScriptAnalyzerRule

这个GitHub Actions工作流文件定义了两个作业：

Run-npm-on-Ubuntu: 在 Ubuntu 虚拟机上运行 npm help 命令。
Run-PSScriptAnalyzer-on-Windows: 在 Windows 虚拟机上安装 PSScriptAnalyzer 模块并列出所有可用的规则。

这两个作业分别展示了如何在不同的操作系统上运行特定的命令和脚本。通过这种方式，你可以确保在不同环境中的一致性和兼容性。

Github Actions常见示例

1. 前端构建部署

举例, 一个部署前端Nodejs项目到Azure云的模版， Deploy Node.js to Azure Web App：

on:
  push:
    branches: [ "master" ]
  workflow_dispatch:  # 允许手动触发工作流

env:
  AZURE_WEBAPP_NAME: your-app-name    # set this to your application's name
  AZURE_WEBAPP_PACKAGE_PATH: '.'      # set this to the path to your web app project, defaults to the repository root
  NODE_VERSION: '20.x'                # set this to the node version to use

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4

    - name: Set up Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: 'npm'

    - name: npm install, build, and test
      run: |
        npm install
        npm run build --if-present
        npm run test --if-present

    - name: Upload artifact for deployment job
      uses: actions/upload-artifact@v3
      with:
        name: node-app
        path: .

  deploy:
    permissions:
      contents: none
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: 'Development'
      url: ${{ steps.deploy-to-webapp.outputs.webapp-url }}

    steps:
    - name: Download artifact from build job
      uses: actions/download-artifact@v3
      with:
        name: node-app

    - name: 'Deploy to Azure WebApp'
      id: deploy-to-webapp
      uses: azure/webapps-deploy@v2
      with:
        app-name: ${{ env.AZURE_WEBAPP_NAME }}
        publish-profile: ${{ secrets.AZURE_WEBAPP_PUBLISH_PROFILE }}
        package: ${{ env.AZURE_WEBAPP_PACKAGE_PATH }}

这个GitHub Actions工作流文件定义了两个主要作业：build 和 deploy。build 作业负责检出代码、设置 Node.js 环境、安装依赖、构建和测试项目，并将构建结果上传为 artifact。 deploy 作业则从 build 作业下载 artifact，并将其部署到 Azure Web App。整个流程自动化了从代码提交到应用部署的全过程。

2. Golang多版本

举例：如下是一个go多版本构建示例

name: Go

on: [push]

jobs:
  build:

    runs-on: ubuntu-latest
    strategy:
      matrix:
        go-version: [ '1.19', '1.20', '1.21.x' ]

    steps:
      - uses: actions/checkout@v4
      - name: Setup Go ${{ matrix.go-version }}
        uses: actions/setup-go@v5
        with:
          go-version: ${{ matrix.go-version }}
      # You can test your matrix by printing the current Go version
      - name: Display Go version
        run: go version

这个GitHub Actions工作流文件主要定义支持多版本golang环境的构建。

3. 容器示例

举例：一个runners为ubuntu的节点里运行docker容器服务

name: CI
on:
  push:
    branches: [ main ]
jobs:
  container-test-job:
    runs-on: ubuntu-latest
    container:
      image: node:18
      env:
        NODE_ENV: development
      ports:
        - 80   # 将容器80端口映射到主机的80端口。
      volumes:
        - my_docker_volume:/volume_mount # 将名为my_docker_volume的Docker卷挂载到容器的/volume_mount路径
      options: --cpus 1 # 限制容器使用的CPU数量为1个核
    steps:
      - name: Check for dockerenv file
        run: (ls /.dockerenv && echo Found dockerenv) || (echo No dockerenv)

这个GitHub Actions工作流文件定义了一个CI任务，该任务在最新的Ubuntu虚拟机上运行，并使用 Node.js 18的Docker镜像。作业配置了环境变量、端口映射、卷挂载和CPU限制。唯一的一个步骤是检查是否存在 .dockerenv 文件，以确认当前环境是否为 Docker 容器。

4. 部署应用到AWS ECS

# This workflow will build and push a new container image to Amazon ECR,
# and then will deploy a new task definition to Amazon ECS, when there is a push to the "master" branch.
#
# To use this workflow, you will need to complete the following set-up steps:
#
# 1. Create an ECR repository to store your images.
#    For example: `aws ecr create-repository --repository-name my-ecr-repo --region us-east-2`.
#    Replace the value of the `ECR_REPOSITORY` environment variable in the workflow below with your repository's name.
#    Replace the value of the `AWS_REGION` environment variable in the workflow below with your repository's region.
#
# 2. Create an ECS task definition, an ECS cluster, and an ECS service.
#    For example, follow the Getting Started guide on the ECS console:
#      https://us-east-2.console.aws.amazon.com/ecs/home?region=us-east-2#/firstRun
#    Replace the value of the `ECS_SERVICE` environment variable in the workflow below with the name you set for the Amazon ECS service.
#    Replace the value of the `ECS_CLUSTER` environment variable in the workflow below with the name you set for the cluster.
#
# 3. Store your ECS task definition as a JSON file in your repository.
#    The format should follow the output of `aws ecs register-task-definition --generate-cli-skeleton`.
#    Replace the value of the `ECS_TASK_DEFINITION` environment variable in the workflow below with the path to the JSON file.
#    Replace the value of the `CONTAINER_NAME` environment variable in the workflow below with the name of the container
#    in the `containerDefinitions` section of the task definition.
#
# 4. Store an IAM user access key in GitHub Actions secrets named `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
#    See the documentation for each action used below for the recommended IAM policies for this IAM user,
#    and best practices on handling the access key credentials.

name: Deploy to Amazon ECS

on:
  push:
    branches: [ "master" ]

env:
  AWS_REGION: MY_AWS_REGION                   # set this to your preferred AWS region, e.g. us-west-1
  ECR_REPOSITORY: MY_ECR_REPOSITORY           # set this to your Amazon ECR repository name
  ECS_SERVICE: MY_ECS_SERVICE                 # set this to your Amazon ECS service name
  ECS_CLUSTER: MY_ECS_CLUSTER                 # set this to your Amazon ECS cluster name
  ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION # set this to the path to your Amazon ECS task definition
                                               # file, e.g. .aws/task-definition.json
  CONTAINER_NAME: MY_CONTAINER_NAME           # set this to the name of the container in the
                                               # containerDefinitions section of your task definition

permissions:
  contents: read

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-latest
    environment: production

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v1
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ env.AWS_REGION }}

    - name: Login to Amazon ECR
      id: login-ecr
      uses: aws-actions/amazon-ecr-login@v1

    - name: Build, tag, and push image to Amazon ECR
      id: build-image
      env:
        ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        IMAGE_TAG: ${{ github.sha }}
      run: |
        # Build a docker container and
        # push it to ECR so that it can
        # be deployed to ECS.
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
        echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

    - name: Fill in the new image ID in the Amazon ECS task definition
      id: task-def
      uses: aws-actions/amazon-ecs-render-task-definition@v1
      with:
        task-definition: ${{ env.ECS_TASK_DEFINITION }}
        container-name: ${{ env.CONTAINER_NAME }}
        image: ${{ steps.build-image.outputs.image }}

    - name: Deploy Amazon ECS task definition
      uses: aws-actions/amazon-ecs-deploy-task-definition@v1
      with:
        task-definition: ${{ steps.task-def.outputs.task-definition }}
        service: ${{ env.ECS_SERVICE }}
        cluster: ${{ env.ECS_CLUSTER }}
        wait-for-service-stability: true

这个GitHub Actions工作流文件定义了一个 CI/CD流程，用于将Docker镜像构建并部署到Amazon ECS。设计内容有：检出代码、配置AWS凭证、登录到Amazon ECR、构建标记并推送镜像到ECR、更新ECS任务定义中的镜像ID、部署更新后的ECS任务定义。

5. 结合Helm部署应用到AKS集群

# This workflow will build and push an application to a Azure Kubernetes Service (AKS) cluster when you push your code
#
# This workflow assumes you have already created the target AKS cluster and have created an Azure Container Registry (ACR)
# The ACR should be attached to the AKS cluster
# For instructions see:
#   - https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal
#   - https://docs.microsoft.com/en-us/azure/container-registry/container-registry-get-started-portal
#   - https://learn.microsoft.com/en-us/azure/aks/cluster-container-registry-integration?tabs=azure-cli#configure-acr-integration-for-existing-aks-clusters
#   - https://github.com/Azure/aks-create-action
#
# To configure this workflow:
#
# 1. Set the following secrets in your repository (instructions for getting these
#    https://docs.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-cli%2Clinux)):
#    - AZURE_CLIENT_ID
#    - AZURE_TENANT_ID
#    - AZURE_SUBSCRIPTION_ID
#
# 2. Set the following environment variables (or replace the values below):
#    - AZURE_CONTAINER_REGISTRY (name of your container registry / ACR)
#    - CONTAINER_NAME (name of the container image you would like to push up to your ACR)
#    - RESOURCE_GROUP (where your cluster is deployed)
#    - CLUSTER_NAME (name of your AKS cluster)
#    - IMAGE_PULL_SECRET_NAME (name of the ImagePullSecret that will be created to pull your ACR image)
#
# 3. Choose the appropriate render engine for the bake step https://github.com/Azure/k8s-bake. The config below assumes Helm.
#    Set your helmChart, overrideFiles, overrides, and helm-version to suit your configuration.
#    - CHART_PATH (path to your helm chart)
#    - CHART_OVERRIDE_PATH (path to your helm chart with override values)
#
# For more information on GitHub Actions for Azure, refer to https://github.com/Azure/Actions
# For more samples to get started with GitHub Action workflows to deploy to Azure, refer to https://github.com/Azure/actions-workflow-samples
# For more options with the actions used below please refer to https://github.com/Azure/login

name: Build and deploy an app to AKS with Helm

on:
  push:
    branches: ["master"]
  workflow_dispatch:

env:
  AZURE_CONTAINER_REGISTRY: "your-azure-container-registry"
  CONTAINER_NAME: "your-container-name"
  RESOURCE_GROUP: "your-resource-group"
  CLUSTER_NAME: "your-cluster-name"
  CHART_PATH: "your-chart-path"
  CHART_OVERRIDE_PATH: "your-chart-override-path"

jobs:
  buildImage:
    permissions:
      contents: read
      id-token: write
    runs-on: ubuntu-latest
    steps:
      # Checks out the repository this file is in
      - uses: actions/checkout@v4

      # Logs in with your Azure credentials
      - name: Azure login
        uses: azure/login@v1.4.6
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      # Builds and pushes an image up to your Azure Container Registry
      - name: Build and push image to ACR
        run: |
          az acr build --image ${{ env.AZURE_CONTAINER_REGISTRY }}.azurecr.io/${{ env.CONTAINER_NAME }}:${{ github.sha }} --registry ${{ env.AZURE_CONTAINER_REGISTRY }} -g ${{ env.RESOURCE_GROUP }} .

  deploy:
    permissions:
      actions: read
      contents: read
      id-token: write
    runs-on: ubuntu-latest
    needs: [buildImage]
    steps:
      # Checks out the repository this file is in
      - uses: actions/checkout@v4

      # Logs in with your Azure credentials
      - name: Azure login
        uses: azure/login@v1.4.6
        with:
          client-id: ${{ secrets.AZURE_CLIENT_ID }}
          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}

      # Use kubelogin to configure your kubeconfig for Azure auth
      - name: Set up kubelogin for non-interactive login
        uses: azure/use-kubelogin@v1
        with:
          kubelogin-version: 'v0.0.25'

      # Retrieves your Azure Kubernetes Service cluster's kubeconfig file
      - name: Get K8s context
        uses: azure/aks-set-context@v3
        with:
          resource-group: ${{ env.RESOURCE_GROUP }}
          cluster-name: ${{ env.CLUSTER_NAME }}
          admin: 'false'
          use-kubelogin: 'true'

      # Runs Helm to create manifest files
      - name: Bake deployment
        uses: azure/k8s-bake@v2
        with:
          renderEngine: "helm"
          helmChart: ${{ env.CHART_PATH }}
          overrideFiles: ${{ env.CHART_OVERRIDE_PATH }}
          overrides: |
            replicas:2
          helm-version: "latest"
        id: bake

      # Deploys application based on manifest files from previous step
      - name: Deploy application
        uses: Azure/k8s-deploy@v4
        with:
          action: deploy
          manifests: ${{ steps.bake.outputs.manifestsBundle }}
          images: |
            ${{ env.AZURE_CONTAINER_REGISTRY }}.azurecr.io/${{ env.CONTAINER_NAME }}:${{ github.sha }}

这个GitHub Actions工作流文件定义了一个CI/CD流程，用于将Docker镜像构建并推送到Azure容器注册表（ACR），然后将应用程序部署到Azure Kubernetes Service (AKS)集群。主要步骤包括：检出代码、使用Azure凭证登录、构建并推送Docker镜像到ACR、获取AKS集群的kubeconfig文件、使用Helm渲染部署清单文件、部署应用程序。

7. 结合Helm部署应用到阿里云ACK集群

# This workflow will build and push a new container image to Alibaba Cloud Container Registry (ACR),
# and then will deploy it to Alibaba Cloud Container Service for Kubernetes (ACK), when there is a push to the "master" branch.
#
# To use this workflow, you will need to complete the following set-up steps:
#
# 1. Create an ACR repository to store your container images.
#    You can use ACR EE instance for more security and better performance.
#    For instructions see https://www.alibabacloud.com/help/doc-detail/142168.htm
#
# 2. Create an ACK cluster to run your containerized application.
#    You can use ACK Pro cluster for more security and better performance.
#    For instructions see https://www.alibabacloud.com/help/doc-detail/95108.htm
#
# 3. Store your AccessKey pair in GitHub Actions secrets named `ACCESS_KEY_ID` and `ACCESS_KEY_SECRET`.
#    For instructions on setting up secrets see: https://developer.github.com/actions/managing-workflows/storing-secrets/
#
# 4. Change the values for the REGION_ID, REGISTRY, NAMESPACE, IMAGE, ACK_CLUSTER_ID, and ACK_DEPLOYMENT_NAME.
#

name: Build and Deploy to ACK

on:
  push:
    branches: [ "master" ]

# Environment variables available to all jobs and steps in this workflow.
env:
  REGION_ID: cn-hangzhou
  REGISTRY: registry.cn-hangzhou.aliyuncs.com
  NAMESPACE: namespace
  IMAGE: repo
  TAG: ${{ github.sha }}
  ACK_CLUSTER_ID: clusterID
  ACK_DEPLOYMENT_NAME: nginx-deployment

  ACR_EE_REGISTRY: myregistry.cn-hangzhou.cr.aliyuncs.com
  ACR_EE_INSTANCE_ID: instanceID
  ACR_EE_NAMESPACE: namespace
  ACR_EE_IMAGE: repo
  ACR_EE_TAG: ${{ github.sha }}

permissions:
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    environment: production

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    # 1.1 Login to ACR
    - name: Login to ACR with the AccessKey pair
      uses: aliyun/acr-login@v1
      with:
        region-id: "${{ env.REGION_ID }}"
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"

    # 1.2 Build and push image to ACR
    - name: Build and push image to ACR
      run: |
        docker build --tag "$REGISTRY/$NAMESPACE/$IMAGE:$TAG" .
        docker push "$REGISTRY/$NAMESPACE/$IMAGE:$TAG"

    # 1.3 Scan image in ACR
    - name: Scan image in ACR
      uses: aliyun/acr-scan@v1
      with:
        region-id: "${{ env.REGION_ID }}"
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"
        repository: "${{ env.NAMESPACE }}/${{ env.IMAGE }}"
        tag: "${{ env.TAG }}"

    # 2.1 (Optional) Login to ACR EE
    - uses: actions/checkout@v4
    - name: Login to ACR EE with the AccessKey pair
      uses: aliyun/acr-login@v1
      with:
        login-server: "https://${{ env.ACR_EE_REGISTRY }}"
        region-id: "${{ env.REGION_ID }}"
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"
        instance-id: "${{ env.ACR_EE_INSTANCE_ID }}"

    # 2.2 (Optional) Build and push image ACR EE
    - name: Build and push image to ACR EE
      run: |
        docker build -t "$ACR_EE_REGISTRY/$ACR_EE_NAMESPACE/$ACR_EE_IMAGE:$TAG" .
        docker push "$ACR_EE_REGISTRY/$ACR_EE_NAMESPACE/$ACR_EE_IMAGE:$TAG"
    # 2.3 (Optional) Scan image in ACR EE
    - name: Scan image in ACR EE
      uses: aliyun/acr-scan@v1
      with:
        region-id: "${{ env.REGION_ID }}"
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"
        instance-id: "${{ env.ACR_EE_INSTANCE_ID }}"
        repository: "${{ env.ACR_EE_NAMESPACE}}/${{ env.ACR_EE_IMAGE }}"
        tag: "${{ env.ACR_EE_TAG }}"

    # 3.1 Set ACK context
    - name: Set K8s context
      uses: aliyun/ack-set-context@v1
      with:
        access-key-id: "${{ secrets.ACCESS_KEY_ID }}"
        access-key-secret: "${{ secrets.ACCESS_KEY_SECRET }}"
        cluster-id: "${{ env.ACK_CLUSTER_ID }}"

    # 3.2 Deploy the image to the ACK cluster
    - name: Set up Kustomize
      run: |-
        curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh"  | bash /dev/stdin 3.8.6
    - name: Deploy
      run: |-
        ./kustomize edit set image REGISTRY/NAMESPACE/IMAGE:TAG=$REGISTRY/$NAMESPACE/$IMAGE:$TAG
        ./kustomize build . | kubectl apply -f -
        kubectl rollout status deployment/$ACK_DEPLOYMENT_NAME
        kubectl get services -o wide

这个GitHub Actions工作流文件定义了一个CI/CD流程，用于将Docker镜像构建并推送到阿里云容器镜像服务（ACR），然后将应用程序部署到阿里云容器服务for Kubernetes（ACK）。具体步骤包括：检出代码、使用AccessKey对ACR进行登录、构建并推送Docker镜像到ACR、扫描ACR中的镜像、设置ACK集群的上下文、设置Kustomize、部署应用程序。

8. 结合Helm部署应用到谷歌云集群

# This workflow will build a docker container, publish it to Google Container
# Registry, and deploy it to GKE when there is a push to the "master"
# branch.
#
# To configure this workflow:
#
# 1. Enable the following Google Cloud APIs:
#
#    - Artifact Registry (artifactregistry.googleapis.com)
#    - Google Kubernetes Engine (container.googleapis.com)
#    - IAM Credentials API (iamcredentials.googleapis.com)
#
#    You can learn more about enabling APIs at
#    https://support.google.com/googleapi/answer/6158841.
#
# 2. Ensure that your repository contains the necessary configuration for your
#    Google Kubernetes Engine cluster, including deployment.yml,
#    kustomization.yml, service.yml, etc.
#
# 3. Create and configure a Workload Identity Provider for GitHub:
#    https://github.com/google-github-actions/auth#preferred-direct-workload-identity-federation.
#
#    Depending on how you authenticate, you will need to grant an IAM principal
#    permissions on Google Cloud:
#
#    - Artifact Registry Administrator (roles/artifactregistry.admin)
#    - Kubernetes Engine Developer (roles/container.developer)
#
#    You can learn more about setting IAM permissions at
#    https://cloud.google.com/iam/docs/manage-access-other-resources
#
# 5. Change the values in the "env" block to match your values.

name: 'Build and Deploy to GKE'

on:
  push:
    branches:
      - '"master"'

env:
  PROJECT_ID: 'my-project' # TODO: update to your Google Cloud project ID
  GAR_LOCATION: 'us-central1' # TODO: update to your region
  GKE_CLUSTER: 'cluster-1' # TODO: update to your cluster name
  GKE_ZONE: 'us-central1-c' # TODO: update to your cluster zone
  DEPLOYMENT_NAME: 'gke-test' # TODO: update to your deployment name
  REPOSITORY: 'samples' # TODO: update to your Artifact Registry docker repository name
  IMAGE: 'static-site'
  WORKLOAD_IDENTITY_PROVIDER: 'projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider' # TODO: update to your workload identity provider

jobs:
  setup-build-publish-deploy:
    name: 'Setup, Build, Publish, and Deploy'
    runs-on: 'ubuntu-latest'
    environment: 'production'

    permissions:
      contents: 'read'
      id-token: 'write'

    steps:
      - name: 'Checkout'
        uses: 'actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332' # actions/checkout@v4

      # Configure Workload Identity Federation and generate an access token.
      #
      # See https://github.com/google-github-actions/auth for more options,
      # including authenticating via a JSON credentials file.
      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@f112390a2df9932162083945e46d439060d66ec2' # google-github-actions/auth@v2
        with:
          workload_identity_provider: '${{ env.WORKLOAD_IDENTITY_PROVIDER }}'

      # Authenticate Docker to Google Cloud Artifact Registry
      - name: 'Docker Auth'
        uses: 'docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567' # docker/login-action@v3
        with:
          username: 'oauth2accesstoken'
          password: '${{ steps.auth.outputs.auth_token }}'
          registry: '${{ env.GAR_LOCATION }}-docker.pkg.dev'

      # Get the GKE credentials so we can deploy to the cluster
      - name: 'Set up GKE credentials'
        uses: 'google-github-actions/get-gke-credentials@6051de21ad50fbb1767bc93c11357a49082ad116' # google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: '${{ env.GKE_CLUSTER }}'
          location: '${{ env.GKE_ZONE }}'

      # Build the Docker image
      - name: 'Build and push Docker container'
        run: |-
          DOCKER_TAG="${GAR_LOCATION}-docker.pkg.dev/${PROJECT_ID}/${REPOSITORY}/${IMAGE}:${GITHUB_SHA}"

          docker build \
            --tag "${DOCKER_TAG}" \
            --build-arg GITHUB_SHA="${GITHUB_SHA}" \
            --build-arg GITHUB_REF="${GITHUB_REF}" \
            .

          docker push "${DOCKER_TAG}"

      # Set up kustomize
      - name: 'Set up Kustomize'
        run: |-
          curl -sfLo kustomize https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv5.4.3/kustomize_v5.4.3_linux_amd64.tar.gz
          chmod u+x ./kustomize

      # Deploy the Docker image to the GKE cluster
      - name: 'Deploy to GKE'
        run: |-
          # replacing the image name in the k8s template
          ./kustomize edit set image LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG=$GAR_LOCATION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$IMAGE:$GITHUB_SHA
          ./kustomize build . | kubectl apply -f -
          kubectl rollout status deployment/$DEPLOYMENT_NAME
          kubectl get services -o wide

这个GitHub Actions工作流文件定义了一个CI/CD流程，用于将Docker镜像构建并推送到Google Cloud Artifact Registry（GAR），然后将应用程序部署到Google Kubernetes Engine（GKE）。

具体步骤包括：检出代码、使用Workload Identity Provider认证到Google Cloud、对Docker进行认证以推送镜像到Artifact Registry、获取GKE集群的凭证、构建并推送Docker镜像到Artifact Registry、设置Kustomize、部署应用程序到GKE。

Github Actions优缺点

通过这几天使用，我觉得GitHub Actions是一个强大的工具，用于自动化软件开发工作流程，如持续集成（CI）、持续部署（CD）、测试、发布等。它直接集成在GitHub平台上，提供了丰富的功能和灵活性。

然而，像所有工具一样，GitHub Actions也有其优点和缺点。以下是对其优缺点的总结：

优点

无缝集成：
- 与 GitHub 无缝集成：GitHub Actions 直接集成在 GitHub 平台内，可以轻松访问仓库中的代码和元数据。
- 自动触发：可以根据代码推送、拉取请求、标签创建等事件自动触发工作流。
丰富的市场：
- Action 市场：GitHub 提供了丰富的 Action 市场，用户可以找到大量的预构建 Action，用于常见的任务，如代码质量检查、部署、通知等。
- 社区支持：庞大的开发者社区提供了大量的资源和最佳实践，帮助用户快速解决问题。
灵活性和可扩展性：
- 自定义工作流：用户可以自定义复杂的多步骤工作流，满足特定需求。
- 环境变量和密钥管理：支持环境变量和密钥管理，确保敏感信息的安全。
- 并行执行：支持并行执行多个任务，提高效率。
内置安全性和审计：
- 安全特性：GitHub 提供了多种安全特性，如依赖项审查、代码扫描等。
- 审计日志：详细的审计日志记录，方便追踪和调试。
成本效益：
- 免费计划：对于开源项目和个人开发者，GitHub 提供了免费的 Actions 使用额度。
- 按需付费：对于企业用户，可以根据实际使用量付费，避免浪费资源。

缺点

学习曲线：
- 复杂性：虽然提供了丰富的功能，但配置和管理复杂的工作流可能需要一定的学习时间和经验。
- 文档和示例：尽管有大量文档和示例，但对于初学者来说，找到合适的资源和最佳实践可能需要一些时间。
性能和资源限制：
- 资源限制：免费计划的资源有限，对于大型项目或高频率的 CI/CD 管道可能不够用。
- 性能波动：在高峰时段，GitHub Actions 的性能可能会受到影响，导致构建和部署速度变慢。
依赖于 GitHub：
- 平台锁定：使用 GitHub Actions 会增加对 GitHub 平台的依赖，迁移成本较高。
- 外部集成：虽然 GitHub Actions 支持与外部工具和服务的集成，但相比其他 CI/CD 工具，可能需要更多的配置和维护。
调试困难：
- 调试工具：虽然提供了日志和输出，但调试复杂的多步骤工作流可能较为困难，尤其是当出现问题时。
- 可视化不足：相比于一些商业 CI/CD 工具，GitHub Actions 的可视化和监控功能较为有限。
安全风险：
- 第三方 Action：使用第三方 Action 可能带来安全风险，需要仔细评估和选择。
- 权限管理：不当的权限管理可能导致安全漏洞，需要谨慎配置。

总结

GitHub Actions是一个功能强大且灵活的CI/CD 工具，特别适合与GitHub集成的项目。它的优点在于无缝集成、丰富的市场、灵活性和安全性。

然而，它也存在一些缺点，如学习曲线较陡、资源限制、平台锁定和调试困难。选择是否使用GitHub Actions 应根据项目的具体需求和团队的技术栈来决定。

对于小型项目和开源项目，GitHub Actions是一个非常不错的选择；对于大型企业项目，可能需要考虑更专业的 CI/CD工具。