0%

发表于 更新于 分类于
本文字数： 12k 阅读时长 ≈ 22 分钟

Git 常用命令速查：从入门到精通

本文整理了 Git 开发中最常用的命令和技巧，涵盖基础操作、分支管理、远程协作、问题排查等场景，是开发者的速查手册。

一、Git 基础配置

1.1 用户信息配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 全局配置（所有仓库）
git config --global user.name "John Doe"
git config --global user.email "john@example.com"

# 查看配置
git config --list
git config user.name
git config user.email

# 编辑配置文件
git config --global --edit

# 常用别名配置
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --all"

1.2 SSH 密钥配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 生成 SSH 密钥
ssh-keygen -t ed25519 -C "your_email@example.com"

# 查看公钥
cat ~/.ssh/id_ed25519.pub

# 添加到 SSH agent
ssh-add ~/.ssh/id_ed25519

# 测试连接 GitHub
ssh -T git@github.com

# 测试连接 GitLab
ssh -T git@gitlab.com

1.3 常用 Git 配置优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 自动修正命令
git config --global help.autocorrect 1

# 默认使用 rebase
git config --global pull.rebase true

# 显示所有分支的图形化日志
git config --global alias.lg "log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit"

# 忽略文件权限变化
git config --global core.filemode false

# 使用 VSCode 作为默认编辑器
git config --global core.editor "code --wait"

# 使用 Beyond Compare 作为 difftool
git config --global diff.tool bc3
git config --global difftool.bc3.trustexitcode true

# 使用 Beyond Compare 作为 mergetool
git config --global merge.tool bc3
git config --global mergetool.bc3.trustexitcode true

二、仓库操作

2.1 创建仓库

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 初始化新仓库
git init
git init my-project

# 克隆远程仓库
git clone https://github.com/user/repo.git
git clone git@github.com:user/repo.git

# 克隆指定分支
git clone -b develop https://github.com/user/repo.git

# 克隆深度（只克隆最近 N 次提交）
git clone --depth 1 https://github.com/user/repo.git

# 克隆子模块
git clone --recursive https://github.com/user/repo.git

2.2 查看状态

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
# 查看仓库状态
git status
git status -s  # 简短格式

# 查看提交历史
git log
git log --oneline
git log --graph --oneline --all
git log -n 5  # 最近 5 条

# 查看某文件的修改历史
git log --follow path/to/file

# 查看某人的提交
git log --author="John"

# 查看时间范围内的提交
git log --since="2 weeks ago"
git log --until="2024-01-01"

# 查看统计信息
git log --stat
git log --shortstat
git log --numstat

# 查看某次提交的详细内容
git show commit_id
git show --stat commit_id

2.3 差异比较

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 工作区 vs 暂存区
git diff

# 暂存区 vs 最新提交
git diff --cached
git diff --staged

# 工作区 vs 最新提交
git diff HEAD

# 两个提交之间的差异
git diff commit1 commit2
git diff commit1..commit2

# 两个分支之间的差异
git diff branch1 branch2

# 只比较某个文件
git diff path/to/file

# 忽略空白字符
git diff -w

# 生成补丁文件
git diff > patch.diff
git diff commit1 commit2 > patch.diff

三、文件操作

3.1 添加文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 添加指定文件
git add file.txt
git add dir/file.txt

# 添加所有文件
git add .
git add -A

# 添加所有修改的文件（不包括新文件）
git add -u

# 交互式添加
git add -p
git add -i

# 查看暂存区内容
git diff --cached

3.2 忽略文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
# 创建 .gitignore 文件
cat > .gitignore << EOF
# 编译产物
*.class
*.o
*.so
build/
dist/
target/

# 依赖目录
node_modules/
vendor/
__pycache__/

# 配置文件
.env
*.local
config.local.js

# IDE 文件
.idea/
.vscode/
*.swp
*.swo

# 系统文件
.DS_Store
Thumbs.db

# 日志文件
*.log
logs/

# 临时文件
tmp/
temp/
*.tmp
EOF

# 查看忽略规则
git check-ignore -v file.txt

# 测试忽略规则
git check-ignore *.log

3.3 删除文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 删除文件（工作区和暂存区）
git rm file.txt

# 删除目录
git rm -r dir/

# 只从暂存区删除（保留工作区文件）
git rm --cached file.txt

# 删除已修改但未暂存的文件
git checkout -- file.txt

# 恢复误删的文件
git checkout HEAD -- file.txt

3.4 移动/重命名文件

1
2
3
4
5
6
7
8
9
# 重命名文件
git mv old_name.txt new_name.txt

# 移动文件
git mv file.txt dir/file.txt

# 重命名后 Git 未识别
git add -A
git status  # Git 会自动识别重命名

四、提交操作

4.1 基本提交

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 提交暂存区
git commit -m "feat: add user authentication"

# 提交并添加描述
git commit -m "feat: add user authentication" -m "Implemented JWT-based authentication"

# 提交所有修改的文件
git commit -am "fix: resolve login bug"

# 修改最后一次提交
git commit --amend
git commit --amend -m "new commit message"

# 提交时跳过预提交钩子
git commit --no-verify

4.2 提交规范

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# Conventional Commits 格式
<type>(<scope>): <subject>

# type 类型
feat:     新功能
fix:      修复 bug
docs:     文档更新
style:    代码格式（不影响功能）
refactor: 重构
test:     测试相关
chore:    构建过程或辅助工具变动

# 示例
feat(auth): add login functionality
fix(api): resolve null pointer exception
docs(readme): update installation guide
style(format): format code with prettier
refactor(core): simplify user service
test(unit): add unit tests for auth module
chore(deps): upgrade dependencies

4.3 撤销提交

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 撤销工作区修改
git checkout -- file.txt
git restore file.txt  # Git 2.23+

# 撤销暂存区修改
git reset HEAD file.txt
git restore --staged file.txt  # Git 2.23+

# 撤销最后一次提交（保留修改）
git reset --soft HEAD~1
git reset --soft commit_id

# 撤销提交并丢弃修改
git reset --hard HEAD~1
git reset --hard commit_id

# 撤销远程已推送的提交（危险！）
git reset --hard HEAD~1
git push --force

# 安全撤销远程提交（推荐）
git revert commit_id
git push

4.4 查看提交历史

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 简洁的提交历史
git log --oneline

# 图形化提交历史
git log --graph --oneline --all

# 带统计信息的提交历史
git log --stat

# 搜索提交信息
git log --grep="bug fix"
git log --grep="feat" --oneline

# 查看某文件的提交历史
git log --follow -- path/to/file

# 查看某人的提交
git log --author="John" --oneline

# 查看时间范围内的提交
git log --since="2 weeks ago" --until="yesterday"

五、分支管理

5.1 分支基础操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
# 查看分支
git branch
git branch -a  # 所有分支（包括远程）
git branch -v  # 显示最后一次提交

# 创建分支
git branch feature/login
git branch feature/login commit_id

# 切换分支
git checkout feature/login
git switch feature/login  # Git 2.23+

# 创建并切换分支
git checkout -b feature/login
git switch -c feature/login  # Git 2.23+

# 删除分支
git branch -d feature/login  # 安全删除（已合并）
git branch -D feature/login  # 强制删除（未合并）

# 重命名分支
git branch -m old-name new-name
git branch -m new-name  # 当前分支

5.2 分支合并

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
# 合并分支到当前分支
git checkout main
git merge feature/login

# 快进合并（不创建合并提交）
git merge --ff-only feature/login

# 禁止快进合并（强制创建合并提交）
git merge --no-ff feature/login

# 合并时压缩提交
git merge --squash feature/login

# 查看合并冲突
git diff --name-only --diff-filter=U
git diff  # 查看冲突内容

# 解决冲突后标记为已解决
git add file.txt

# 取消合并
git merge --abort

5.3 分支变基（Rebase）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 变基操作
git checkout feature/login
git rebase main

# 交互式变基
git rebase -i HEAD~3
git rebase -i commit_id

# 变基交互命令
# pick:   使用提交
# reword: 使用提交，修改提交信息
# edit:   使用提交，暂停以便修改
# squash: 使用提交，压缩到上一个提交
# fixup:  使用提交，丢弃提交信息
# drop:   删除提交

# 继续变基
git rebase --continue

# 跳过当前提交
git rebase --skip

# 取消变基
git rebase --abort

# 变基到上游分支
git pull --rebase

5.4 分支管理最佳实践

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 查看已合并的分支
git branch --merged

# 查看未合并的分支
git branch --no-merged

# 查看分支的提交关系
git log --oneline --graph --all --decorate

# 清理已合并的本地分支
git branch --merged | grep -v "\*\|main\|develop" | xargs -n 1 git branch -d

# 查看远程跟踪分支
git branch -r

# 删除远程已删除的分支
git fetch -p
git remote prune origin

六、远程协作

6.1 远程仓库操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# 查看远程仓库
git remote
git remote -v

# 添加远程仓库
git remote add origin https://github.com/user/repo.git
git remote add origin git@github.com:user/repo.git

# 修改远程仓库 URL
git remote set-url origin https://github.com/user/new-repo.git

# 删除远程仓库
git remote remove origin

# 重命名远程仓库
git remote rename origin upstream

# 获取远程仓库信息
git remote show origin

6.2 拉取和推送

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# 拉取远程分支
git fetch origin
git fetch origin feature/login

# 拉取并合并
git pull origin main
git pull  # 默认当前分支的 upstream

# 拉取并变基
git pull --rebase origin main

# 推送分支
git push origin feature/login
git push  # 推送当前分支

# 推送并设置 upstream
git push -u origin feature/login

# 强制推送（危险！）
git push --force
git push --force-with-lease  # 更安全

# 推送所有分支
git push --all origin

# 推送所有标签
git push --tags origin

# 删除远程分支
git push origin --delete feature/login
git push origin :feature/login  # 旧语法

6.3 标签管理

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 查看标签
git tag
git tag -l "v1.*"

# 创建标签
git tag v1.0.0
git tag v1.0.0 commit_id

# 创建带注释的标签
git tag -a v1.0.0 -m "Release version 1.0.0"

# 查看标签信息
git show v1.0.0

# 推送标签
git push origin v1.0.0
git push --tags

# 删除本地标签
git tag -d v1.0.0

# 删除远程标签
git push origin --delete v1.0.0
git push origin :refs/tags/v1.0.0

# 检出标签
git checkout v1.0.0

6.4 Git Flow 工作流

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 初始化 Git Flow
git flow init

# 开始新功能
git flow feature start login
git flow feature finish login

# 发布新版本
git flow release start 1.0.0
git flow release finish 1.0.0

# 修复生产 bug
git flow hotstart critical-bug
git flow hotfix finish critical-bug

七、高级技巧

7.1 暂存（Stash）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 暂存当前修改
git stash
git stash save "WIP: login feature"

# 查看暂存列表
git stash list

# 应用暂存（不删除）
git stash apply
git stash apply stash@{1}

# 应用并删除暂存
git stash pop
git stash pop stash@{1}

# 删除暂存
git stash drop
git stash drop stash@{1}

# 清空所有暂存
git stash clear

# 从暂存创建分支
git stash branch feature/login stash@{0}

# 暂存未跟踪的文件
git stash -u
git stash --include-untracked

# 暂存所有文件（包括已删除）
git stash -a
git stash --all

7.2 樱桃拣选（Cherry-pick）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 拣选单个提交
git cherry-pick commit_id

# 拣选多个提交
git cherry-pick commit1 commit2 commit3

# 拣选提交范围
git cherry-pick commit1..commit2

# 拣选时不提交
git cherry-pick --no-commit commit_id

# 拣选时编辑提交信息
git cherry-pick --edit commit_id

# 取消樱桃拣选
git cherry-pick --abort

# 继续樱桃拣选（解决冲突后）
git cherry-pick --continue

7.3 二分查找（Bisect）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 开始二分查找
git bisect start

# 标记当前为坏版本
git bisect bad

# 标记某版本为好版本
git bisect good v1.0.0

# Git 自动切换到中间版本，测试后继续标记
git bisect good  # 或 git bisect bad

# 自动二分查找
git bisect run ./test-script.sh

# 结束二分查找
git bisect reset

# 查看二分查找日志
git bisect log

7.4 子模块（Submodule）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 添加子模块
git submodule add https://github.com/user/lib.git libs/lib

# 初始化子模块
git submodule init

# 更新子模块
git submodule update
git submodule update --init --recursive

# 查看子模块状态
git submodule status

# 更新子模块到最新版本
git submodule update --remote

# 删除子模块
git submodule deinit libs/lib
git rm libs/lib
rm -rf .git/modules/libs/lib

7.5 Git Hooks

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Git Hooks 目录
ls .git/hooks/

# 常用 Hooks
pre-commit      # 提交前检查
pre-push        # 推送前检查
commit-msg      # 提交信息检查
post-merge      # 合并后执行

# 启用 Hook
cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

# 示例：pre-commit 检查
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
# 检查是否有调试代码
if git diff --cached | grep -E "console\.log|debugger"; then
    echo "Error: Found debug code"
    exit 1
fi

# 运行代码检查
npm run lint
EOF

chmod +x .git/hooks/pre-commit

八、问题排查

8.1 查看修改历史

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 谁修改了某行代码
git blame file.txt
git blame -L 10,20 file.txt  # 查看特定行

# 查看某次提交引入的修改
git show commit_id

# 查看某文件的修改历史
git log --follow -- path/to/file

# 查找引入 bug 的提交
git bisect start
git bisect bad
git bisect good v1.0.0

8.2 恢复丢失的提交

1
2
3
4
5
6
7
8
9
10
11
12
13
# 查看 reflog
git reflog
git reflog show --all

# 恢复丢失的提交
git reset --hard HEAD@{1}
git checkout -b recovery-branch commit_id

# 查看 dangling 提交
git fsck --lost-found

# 恢复 dangling 提交
git cherry-pick commit_id

8.3 解决常见问题

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 问题：提交信息写错
git commit --amend -m "correct message"

# 问题：漏提交了文件
git add forgotten_file.txt
git commit --amend --no-edit

# 问题：提交到了错误的分支
git reset --hard HEAD~1  # 撤销提交
git checkout correct-branch
git cherry-pick original-branch

# 问题：合并冲突
git mergetool  # 使用图形化工具
git diff --name-only --diff-filter=U  # 查看冲突文件

# 问题：误删了分支
git reflog
git branch recovered-branch commit_id

# 问题：Git 仓库损坏
git fsck
git gc

8.4 性能优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 清理不必要的文件
git gc
git gc --aggressive

# 清理远程跟踪分支
git remote prune origin

# 查看仓库大小
git count-objects -v
git du -sh .git/objects/*

# 查找大文件
git rev-list --objects --all | git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | awk '/^blob/ {print substr($0,6)}' | sort -k2 -nr | head -20

# 从历史中删除大文件
git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch path/to/large-file' --prune-empty --tag-name-filter cat -- --all

九、实用脚本

9.1 日常开发脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
# 快速创建功能分支
function git-feat() {
    git checkout -b "feat/$1"
}

# 快速创建修复分支
function git-fix() {
    git checkout -b "fix/$1"
}

# 提交并推送
function git-commit-push() {
    git add -A
    git commit -m "$1"
    git push -u origin $(git branch --show-current)
}

# 同步主分支
function git-sync-main() {
    git fetch origin
    git rebase origin/main
}

# 清理已合并分支
function git-cleanup() {
    git branch --merged | grep -v "\*\|main\|develop" | xargs -n 1 git branch -d
}

# 查看今日提交
function git-today() {
    git log --since="today" --author="$(git config user.name)"
}

9.2 Git 配置模板

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
# .gitconfig 模板
[alias]
    lg = log --color --graph --pretty=format:'%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset' --abbrev-commit
    st = status -s
    co = checkout
    br = branch
    ci = commit
    last = log -1 HEAD
    unstage = reset HEAD --
    who = blame -L -20,-0
    
[user]
    name = Your Name
    email = your.email@example.com
    
[core]
    editor = code --wait
    autocrlf = input
    filemode = false
    
[pull]
    rebase = true
    
[push]
    default = simple
    
[merge]
    tool = vscode
    
[difftool "vscode"]
    cmd = code --wait --diff $LOCAL $REMOTE

十、总结

Git 是开发者必备的工具，掌握常用命令可以大幅提升开发效率。关键要点：

  1. 基础操作：add、commit、push、pull
  2. 分支管理：branch、checkout、merge、rebase
  3. 问题排查：log、diff、blame、reflog
  4. 高级技巧：stash、cherry-pick、bisect

建议将常用命令配置为别名，并建立适合自己的工作流。

参考资料：

发表于 更新于 分类于
本文字数： 21k 阅读时长 ≈ 39 分钟

OpenClaw K8s 部署实践：从 CrashLoopBackOff 到稳定运行

摘要：本文详细记录了将 OpenClaw AI Agent 框架部署到 Kubernetes 集群的完整实践过程。从最初的 CephFS 挂载失败、ImagePullBackOff、CrashLoopBackOff 三大拦路虎，到最终实现稳定运行。包含完整的 YAML 配置、故障排查思路、性能优化方案，以及生产环境的最佳实践建议。

关键词：OpenClaw、Kubernetes、CephFS、容器化部署、故障排查、AI Agent

一、背景与目标

1.1 为什么选择 K8s 部署 OpenClaw？

OpenClaw 是一个本地优先的 AI Agent 框架，传统部署方式依赖本地环境和文件系统。随着业务规模扩大，我们面临以下挑战：

  • 资源隔离需求：多个 Agent 实例需要独立的工作空间和配置
  • 高可用要求：Gateway 服务需要 7×24 小时稳定运行
  • 弹性扩展：根据负载动态调整计算资源
  • 集中管理：统一监控、日志、备份策略

Kubernetes 提供了理想的解决方案：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │              openclaw Namespace                      │    │
│  │  ┌─────────────────┐  ┌─────────────────┐           │    │
│  │  │  openclaw-gw    │  │  openclaw-browser│          │    │
│  │  │  (Gateway Pod)  │  │  (Browser Pod)  │           │    │
│  │  └────────┬────────┘  └────────┬────────┘           │    │
│  │           │                    │                     │    │
│  │  ┌────────▼────────────────────▼────────┐           │    │
│  │  │         PVC (200Gi CephFS)           │           │    │
│  │  │  /root/.openclaw/workspace           │           │    │
│  │  │  /root/.openclaw/config              │           │    │
│  │  └──────────────────────────────────────┘           │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

1.2 部署目标

指标 目标值 实际达成
启动时间 < 5 分钟 3 分钟
服务可用性 99.9% 99.95%
存储持久化 100% 100%
配置热更新 支持 支持
自动恢复 支持 支持

二、架构设计

2.1 整体架构图

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
graph TB
    subgraph "Kubernetes Cluster"
        subgraph "openclaw Namespace"
            GW[openclaw-gateway<br/>Deployment: 1 Replica]
            Browser[openclaw-browser<br/>Deployment: 1 Replica]
            PVC[(openclaw-data-pvc<br/>200Gi CephFS)]
            CM[openclaw-config<br/>ConfigMap]
            SA[openclaw-sa<br/>ServiceAccount]
        end
        
        LB[LoadBalancer Service<br/>Port: 18789]
        BrowserSvc[ClusterIP Service<br/>Port: 18791]
    end
    
    subgraph "External Services"
        DashScope[阿里云百炼<br/>qwen3.5-plus]
        Feishu[飞书机器人]
        MinIO[MinIO 备份<br/>hb.test]
    end
    
    User[用户] -->|WebSocket| LB
    LB --> GW
    GW -->|HTTP| BrowserSvc
    BrowserSvc --> Browser
    GW -->|Mount| PVC
    Browser -->|Mount| PVC
    GW -->|API| DashScope
    GW -->|Webhook| Feishu
    PVC -->|Daily Backup| MinIO

2.2 存储架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
graph LR
    subgraph "PVC: openclaw-data-pvc"
        subgraph "config/"
            openclaw_json[openclaw.json]
            models_json[models.json]
        end
        
        subgraph "workspace/"
            SOUL[SOUL.md]
            AGENTS[AGENTS.md]
            MEMORY[MEMORY.md]
            docs[docs/]
            skills[skills/]
            memory[memory/]
        end
        
        subgraph "logs/"
            gateway_log[gateway.log]
            browser_log[browser.log]
        end
    end
    
    GW_Pod[Gateway Pod] -->|RWM| PVC
    Browser_Pod[Browser Pod] -->|RWM| PVC

2.3 网络架构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
┌─────────────────────────────────────────────────────────────┐
│                    外部访问层                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Feishu    │  │   Browser   │  │   Metrics   │         │
│  │   Webhook   │  │   Control   │  │   Endpoint  │         │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘         │
│         │                │                │                 │
│         ▼                ▼                ▼                 │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Gateway Service (NodePort)             │   │
│  │                    Port: 18789                       │   │
│  └─────────────────────────────────────────────────────┘   │
│         │                │                │                 │
│         ▼                ▼                ▼                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │   Gateway   │  │   Browser   │  │   Metrics   │         │
│  │   Pod       │  │   Pod       │  │   Server    │         │
│  │   :18789    │  │   :18791    │  │   :18790    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

三、部署实施

3.1 环境准备

3.1.1 集群要求

资源 最低配置 推荐配置
CPU 2 Core 4 Core
内存 4Gi 8Gi
存储 50Gi 200Gi
网络 100Mbps 1Gbps

3.1.2 存储类配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# storageclass-cephfs.yaml
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: csi-cephfs-sc
provisioner: cephfs.csi.ceph.com
parameters:
  clusterID: rook-ceph
  fsName: myfs
  pool: myfs-data0
  csi.storage.k8s.io/provisioner-secret-name: rook-csi-cephfs-provisioner
  csi.storage.k8s.io/provisioner-secret-namespace: rook-ceph
  csi.storage.k8s.io/controller-expand-secret-name: rook-csi-cephfs-provisioner
  csi.storage.k8s.io/controller-expand-secret-namespace: rook-ceph
  csi.storage.k8s.io/node-stage-secret-name: rook-csi-cephfs-node
  csi.storage.k8s.io/node-stage-secret-namespace: rook-ceph
reclaimPolicy: Retain
allowVolumeExpansion: true
mountOptions:
  - discard

3.2 核心配置文件

3.2.1 PVC 配置（单 PVC 方案）

踩坑记录 #1：最初设计了 5 个独立 PVC（config/workspace/logs/backups/temp），导致 CephFS 挂载失败。简化为单 PVC 方案后问题解决。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 03-pvc.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: openclaw-data-pvc
  namespace: openclaw
  labels:
    app: openclaw
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 200Gi
  storageClassName: csi-cephfs-sc

3.2.2 ConfigMap 配置

1
2
3
4
5
6
7
8
9
10
11
# 05-configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: openclaw-config
  namespace: openclaw
data:
  OPENCLAW_ALLOW_UNCONFIGURED: "true"
  OPENCLAW_HOME: "/root/.openclaw"
  DASHSCOPE_API_KEY: "sk-xxxxxxxxxxxxxxxx"
  LOG_LEVEL: "info"

3.2.3 Deployment 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
# 06-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: openclaw-gateway
  namespace: openclaw
  labels:
    app: openclaw-gateway
spec:
  replicas: 1
  selector:
    matchLabels:
      app: openclaw-gateway
  template:
    metadata:
      labels:
        app: openclaw-gateway
    spec:
      serviceAccountName: openclaw-sa
      containers:
        - name: gateway
          image: hb.test/crystalforge/openclaw-cn-base:1.0.0
          imagePullPolicy: IfNotPresent
          command:
            - /bin/sh
            - -c
            - |
              echo "Starting OpenClaw Gateway..."
              openclaw gateway start --allow-unconfigured
          envFrom:
            - configMapRef:
                name: openclaw-config
          ports:
            - containerPort: 18789
              name: gateway
            - containerPort: 18790
              name: metrics
            - containerPort: 18791
              name: browser
          volumeMounts:
            - name: data-volume
              mountPath: /root/.openclaw
              subPath: config
            - name: data-volume
              mountPath: /root/.openclaw/workspace
              subPath: workspace
            - name: data-volume
              mountPath: /root/.openclaw/logs
              subPath: logs
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              cpu: "2000m"
              memory: "4Gi"
          livenessProbe:
            httpGet:
              path: /health
              port: 18790
            initialDelaySeconds: 30
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 18790
            initialDelaySeconds: 10
            periodSeconds: 5
      volumes:
        - name: data-volume
          persistentVolumeClaim:
            claimName: openclaw-data-pvc
      restartPolicy: Always

3.2.4 Service 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 07-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: openclaw-gateway
  namespace: openclaw
spec:
  type: NodePort
  selector:
    app: openclaw-gateway
  ports:
    - name: gateway
      port: 18789
      targetPort: 18789
      nodePort: 30789
    - name: browser
      port: 18791
      targetPort: 18791
    - name: metrics
      port: 18790
      targetPort: 18790

3.3 一键部署脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
#!/bin/bash
# 10-deploy.sh - OpenClaw K8s 一键部署脚本

set -e

NAMESPACE="openclaw"
IMAGE="hb.test/crystalforge/openclaw-cn-base:1.0.0"

echo "🚀 开始部署 OpenClaw to Kubernetes..."

# 1. 创建命名空间
echo "📦 创建命名空间: $NAMESPACE"
kubectl create namespace $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

# 2. 应用存储配置
echo "💾 应用 PVC 配置..."
kubectl apply -f 03-pvc.yaml -n $NAMESPACE

# 3. 应用 RBAC 配置
echo "🔐 应用 RBAC 配置..."
kubectl apply -f 04-serviceaccount.yaml -n $NAMESPACE

# 4. 应用 ConfigMap
echo "⚙️  应用 ConfigMap..."
kubectl apply -f 05-configmap.yaml -n $NAMESPACE

# 5. 应用 Deployment
echo "🎯 应用 Deployment..."
kubectl apply -f 06-deployment.yaml -n $NAMESPACE

# 6. 应用 Service
echo "🌐 应用 Service..."
kubectl apply -f 07-service.yaml -n $NAMESPACE

# 7. 等待 Pod 就绪
echo "⏳ 等待 Pod 就绪..."
kubectl wait --for=condition=ready pod -l app=openclaw-gateway -n $NAMESPACE --timeout=300s

# 8. 显示访问信息
echo ""
echo "✅ 部署完成！"
echo ""
echo "📊 访问信息:"
echo "   Gateway WebSocket: ws://<node-ip>:30789"
echo "   Browser Control:   http://<node-ip>:18791"
echo "   Metrics Endpoint:  http://<node-ip>:18790/metrics"
echo ""
echo "🔍 查看日志:"
echo "   kubectl logs -l app=openclaw-gateway -n $NAMESPACE -f"
echo ""
echo "🛠️  故障排查:"
echo "   kubectl describe pod -l app=openclaw-gateway -n $NAMESPACE"
echo "   kubectl get pvc -n $NAMESPACE"
echo ""

四、故障排查实战

4.1 问题 #1: CephFS 挂载失败

现象

1
2
3
$ kubectl get pod -n openclaw
NAME                                READY   STATUS             RESTARTS   AGE
openclaw-gateway-6d8f9c7b5-x2k9m   0/1     ContainerCreating  0          5m
1
2
3
4
5
6
7
8
9
$ kubectl describe pod openclaw-gateway-6d8f9c7b5-x2k9m -n openclaw
Events:
  Type     Reason       Age   From               Message
  ----     ------       ----  ----               -------
  Warning  FailedMount  2m    kubelet            MountVolume.SetUp failed for volume "pvc-xxx" :
           mount failed: exit status 32
           Mounting command: mount
           Mounting arguments: -t ceph <redacted>
           Output: mount: mounting <redacted> failed: Connection timed out

排查过程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 1. 检查 Ceph 集群状态
$ kubectl rook-ceph ceph status
  cluster:
    id:     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    health: HEALTH_OK
  
# 2. 检查 StorageClass
$ kubectl get sc csi-cephfs-sc
NAME            PROVISIONER       RECLAIMPOLICY   VOLUMEBINDINGMODE   ALLOWVOLUMEEXPANSION   AGE
csi-cephfs-sc   cephfs.csi.ceph.com   Retain        Immediate           true                   30d

# 3. 检查 PVC 状态
$ kubectl get pvc -n openclaw
NAME                  STATUS   VOLUME   CAPACITY   ACCESSMODES   STORAGECLASS    AGE
openclaw-data-pvc     Bound    pvc-xxx  200Gi      RWX           csi-cephfs-sc   5m

根因分析

问题：最初设计了 5 个独立 PVC，每个 PVC 都需要独立的 CephFS 子卷。Ceph CSI 驱动在短时间内创建多个子卷时出现资源竞争，导致挂载超时。

解决方案：简化为单 PVC 方案，使用 subPath 在容器内部分隔不同目录。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
# 优化前：5 个独立 PVC ❌
volumes:
  - name: config-volume
    persistentVolumeClaim:
      claimName: openclaw-config-pvc
  - name: workspace-volume
    persistentVolumeClaim:
      claimName: openclaw-workspace-pvc
  - name: logs-volume
    persistentVolumeClaim:
      claimName: openclaw-logs-pvc
  - name: backups-volume
    persistentVolumeClaim:
      claimName: openclaw-backups-pvc
  - name: temp-volume
    persistentVolumeClaim:
      claimName: openclaw-temp-pvc

# 优化后：单 PVC + subPath ✅
volumes:
  - name: data-volume
    persistentVolumeClaim:
      claimName: openclaw-data-pvc
volumeMounts:
  - name: data-volume
    mountPath: /root/.openclaw
    subPath: config
  - name: data-volume
    mountPath: /root/.openclaw/workspace
    subPath: workspace
  - name: data-volume
    mountPath: /root/.openclaw/logs
    subPath: logs

验证

1
2
3
$ kubectl get pod -n openclaw
NAME                                READY   STATUS    RESTARTS   AGE
openclaw-gateway-6d8f9c7b5-x2k9m   1/1     Running   0          2m

4.2 问题 #2: ImagePullBackOff

现象

1
2
3
$ kubectl get pod -n openclaw
NAME                                READY   STATUS             RESTARTS   AGE
openclaw-gateway-6d8f9c7b5-x2k9m   0/1     ImagePullBackOff   0          3m
1
2
3
4
5
6
7
8
$ kubectl describe pod openclaw-gateway-6d8f9c7b5-x2k9m -n openclaw
Events:
  Type     Reason     Age   From               Message
  ----     ------     ----  ----               -------
  Warning  Failed     2m    kubelet            Failed to pull image "hb.test/crystalforge/openclaw-cn-base:1.0.0":
           rpc error: code = NotFound desc = failed to pull and unpack image
           "hb.test/crystalforge/openclaw-cn-base:1.0.0": failed to resolve reference
  Warning  Failed     1m    kubelet            Error: ImagePullBackOff

排查过程

1
2
3
4
5
6
7
8
9
10
11
# 1. 检查镜像是否存在
$ docker pull hb.test/crystalforge/openclaw-cn-base:1.0.0
Error response from daemon: Get https://hb.test/v2/: dial tcp: lookup hb.test: no such host

# 2. 检查 /etc/hosts 配置
$ cat /etc/hosts | grep hb.test
192.168.100.181  hb.test

# 3. 在 K8s 节点上验证
$ ssh node1 "docker pull hb.test/crystalforge/openclaw-cn-base:1.0.0"
# 成功拉取

根因分析

问题：K8s 节点的 /etc/hosts 没有配置 hb.test 域名解析，导致无法访问内部 Harbor 仓库。

解决方案：

  1. 方案 A：在所有 K8s 节点的 /etc/hosts 添加记录
  2. 方案 B：使用 imagePullPolicy: IfNotPresent + 节点预拉取

我们选择方案 B（更简单可靠）：

1
2
3
4
containers:
  - name: gateway
    image: hb.test/crystalforge/openclaw-cn-base:1.0.0
    imagePullPolicy: IfNotPresent  # 关键配置

预拉取脚本

1
2
3
4
5
6
7
8
9
#!/bin/bash
# 在所有 K8s 节点预拉取镜像
NODES=("node1" "node2" "node3")
IMAGE="hb.test/crystalforge/openclaw-cn-base:1.0.0"

for node in "${NODES[@]}"; do
    echo "📦 拉取镜像到节点：$node"
    ssh $node "docker pull $IMAGE"
done

4.3 问题 #3: CrashLoopBackOff

现象

1
2
3
$ kubectl get pod -n openclaw
NAME                                READY   STATUS             RESTARTS   AGE
openclaw-gateway-6d8f9c7b5-x2k9m   0/1     CrashLoopBackOff   5          10m
1
2
3
$ kubectl logs openclaw-gateway-6d8f9c7b5-x2k9m -n openclaw
Error: configuration file not found at /root/.openclaw/openclaw.json
Use --allow-unconfigured to start without configuration

排查过程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 检查 ConfigMap
$ kubectl get cm openclaw-config -n openclaw -o yaml
# ConfigMap 存在，但没有包含配置文件

# 2. 检查 PVC 内容
$ kubectl run debug --rm -i --restart=Never --image=busybox -n openclaw \
    --overrides='{"spec":{"volumes":[{"name":"data-volume","persistentVolumeClaim":{"claimName":"openclaw-data-pvc"}}],"containers":[{"name":"debug","image":"busybox","command":["sleep","3600"],"volumeMounts":[{"name":"data-volume","mountPath":"/data","subPath":"config"}]}]}}'

$ kubectl exec debug -n openclaw -- ls -la /data
# 目录为空！

# 3. 检查启动命令
$ kubectl describe pod openclaw-gateway -n openclaw | grep -A5 "Command:"
Command:
  /bin/sh
  -c
  openclaw gateway start

根因分析

问题：OpenClaw Gateway 启动时需要配置文件 openclaw.json，但 PVC 是空的。Gateway 没有 --allow-unconfigured 参数时会自动退出。

解决方案：

  1. 方案 A：预先在 PVC 中放置配置文件
  2. 方案 B：添加 --allow-unconfigured 启动参数

我们选择方案 B（更灵活）：

1
2
3
4
5
6
7
8
containers:
  - name: gateway
    command:
      - /bin/sh
      - -c
      - |
        echo "Starting OpenClaw Gateway..."
        openclaw gateway start --allow-unconfigured  # 关键参数

配置文件更新方法

配置文件存储在 PVC 中，更新需要特殊方法：

1
2
3
4
5
6
7
8
# 方法：通过临时 Pod 更新
kubectl run config-updater --rm -i --restart=Never \
  --image=busybox -n openclaw \
  --overrides='{"spec":{"volumes":[{"name":"data-volume","persistentVolumeClaim":{"claimName":"openclaw-data-pvc"}}],"containers":[{"name":"updater","image":"busybox","command":["sleep","3600"],"volumeMounts":[{"name":"data-volume","mountPath":"/data","subPath":"config"}]}]}}'

kubectl cp /tmp/openclaw.json openclaw/config-updater:/data/openclaw.json
kubectl delete pod config-updater -n openclaw
kubectl rollout restart deployment openclaw-gateway -n openclaw

4.4 问题 #4: 模型配置错误

现象

1
2
$ kubectl logs openclaw-gateway -n openclaw | grep -i error
Error: model 'qwen-plus' not found in provider 'bailian'

排查过程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 1. 检查配置文件
$ kubectl exec openclaw-gateway -n openclaw -- cat /root/.openclaw/openclaw.json | jq '.models'
{
  "default": "qwen-plus",
  "providers": {
    "bailian": {
      "baseUrl": "https://dashscope.aliyuncs.com/v1"
    }
  }
}

# 2. 检查 DashScope 可用模型
$ curl -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    https://dashscope.aliyuncs.com/v1/models | jq '.data[].id'
"qwen3.5-plus"
"qwen-max"
"qwen-plus"  # 已下线

根因分析

问题：阿里云 DashScope 已将 qwen-plus 模型下线，替换为 qwen3.5-plus。

解决方案：更新配置文件

1
2
3
4
5
6
7
8
9
10
11
{
  "models": {
    "default": "bailian/qwen3.5-plus",
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-xxxxxxxxxxxxxxxx"
      }
    }
  }
}

五、性能测试与优化

5.1 启动性能

阶段 优化前 优化后 提升
镜像拉取 2m 30s 0s (本地) 100%
PVC 挂载 1m 20s 20s 75%
服务启动 45s 30s 33%
总计 4m 35s 50s 82%

5.2 运行性能

5.2.1 资源使用

1
2
3
$ kubectl top pod -n openclaw
NAME                                CPU(cores)   MEMORY(bytes)
openclaw-gateway-6d8f9c7b5-x2k9m   250m         1.2Gi

5.2.2 响应延迟

操作 P50 P95 P99
WebSocket 连接 15ms 45ms 120ms
消息处理 200ms 800ms 1.5s
文件读写 5ms 20ms 50ms
模型调用 1.2s 3.5s 5.8s

5.3 优化建议

5.3.1 资源限制优化

1
2
3
4
5
6
7
resources:
  requests:
    cpu: "500m"    # 从 250m 提升
    memory: "2Gi"  # 从 1Gi 提升
  limits:
    cpu: "4000m"   # 从 2000m 提升
    memory: "8Gi"  # 从 4Gi 提升

5.3.2 健康检查优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
livenessProbe:
  httpGet:
    path: /health
    port: 18790
  initialDelaySeconds: 60  # 从 30s 提升
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 18790
  initialDelaySeconds: 30  # 从 10s 提升
  periodSeconds: 5
  timeoutSeconds: 3
  failureThreshold: 3

5.3.3 日志优化

1
2
3
4
5
6
7
8
9
10
11
12
# 添加日志收集侧车
containers:
  - name: log-collector
    image: fluent/fluent-bit:latest
    volumeMounts:
      - name: data-volume
        mountPath: /var/log
        subPath: logs
    resources:
      requests:
        cpu: "50m"
        memory: "50Mi"

六、监控与告警

6.1 Prometheus 配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# prometheus-servicemonitor.yaml
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: openclaw
  namespace: openclaw
spec:
  selector:
    matchLabels:
      app: openclaw-gateway
  endpoints:
    - port: metrics
      interval: 30s
      path: /metrics

6.2 关键指标

指标 阈值 告警级别
Pod 重启次数 > 3 次/小时 Warning
CPU 使用率 > 80% Warning
内存使用率 > 90% Critical
消息处理延迟 > 5s Warning
模型调用失败率 > 5% Critical

6.3 Grafana 仪表盘

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "dashboard": {
    "title": "OpenClaw Gateway",
    "panels": [
      {
        "title": "CPU Usage",
        "targets": [
          {
            "expr": "rate(process_cpu_seconds_total{job=\"openclaw\"}[5m])"
          }
        ]
      },
      {
        "title": "Memory Usage",
        "targets": [
          {
            "expr": "process_resident_memory_bytes{job=\"openclaw\"}"
          }
        ]
      },
      {
        "title": "Message Processing Latency",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(openclaw_message_duration_seconds_bucket[5m]))"
          }
        ]
      }
    ]
  }
}

七、备份与恢复

7.1 备份策略

类型 频率 保留期 存储位置
配置文件 每日 02:00 90 天 MinIO
工作空间 每日 02:00 90 天 MinIO
日志文件 每周 03:00 180 天 MinIO

7.2 备份脚本

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/bin/bash
# backup-openclaw.sh

BACKUP_DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_BUCKET="openclaw-backups"
MINIO_ENDPOINT="https://img.sharezone.cn"
MINIO_ACCESS_KEY="minioadminjohn"
MINIO_SECRET_KEY="Adbdedkkf@12321"

# 1. 创建备份目录
BACKUP_DIR="/tmp/openclaw-backup-$BACKUP_DATE"
mkdir -p $BACKUP_DIR

# 2. 从 PVC 复制数据
kubectl run backup-agent --rm -i --restart=Never \
  --image=busybox -n openclaw \
  --overrides='{"spec":{"volumes":[{"name":"data-volume","persistentVolumeClaim":{"claimName":"openclaw-data-pvc"}}],"containers":[{"name":"backup","image":"busybox","command":["tar","czf","/data/backup.tar.gz","-C","/data","."],"volumeMounts":[{"name":"data-volume","mountPath":"/data"}]}]}}'

# 3. 下载到本地
kubectl cp openclaw/backup-agent:/data/backup.tar.gz $BACKUP_DIR/

# 4. 上传到 MinIO
mc alias set my-minio $MINIO_ENDPOINT $MINIO_ACCESS_KEY $MINIO_SECRET_KEY
mc cp $BACKUP_DIR/backup.tar.gz my-minio/$BACKUP_BUCKET/$BACKUP_DATE.tar.gz

# 5. 清理本地临时文件
rm -rf $BACKUP_DIR

echo "✅ 备份完成：$BACKUP_DATE"

7.3 恢复流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
#!/bin/bash
# restore-openclaw.sh

RESTORE_DATE=$1  # 格式：YYYYMMDD_HHMMSS

if [ -z "$RESTORE_DATE" ]; then
    echo "用法：$0 <备份日期>"
    exit 1
fi

# 1. 从 MinIO 下载备份
mc cp my-minio/openclaw-backups/$RESTORE_DATE.tar.gz /tmp/

# 2. 停止 Gateway
kubectl scale deployment openclaw-gateway --replicas=0 -n openclaw

# 3. 清空 PVC
kubectl run restore-agent --rm -i --restart=Never \
  --image=busybox -n openclaw \
  --overrides='{"spec":{"volumes":[{"name":"data-volume","persistentVolumeClaim":{"claimName":"openclaw-data-pvc"}}],"containers":[{"name":"restore","image":"busybox","command":["rm","-rf","/data/*"],"volumeMounts":[{"name":"data-volume","mountPath":"/data"}]}]}}'

# 4. 恢复数据
kubectl cp /tmp/$RESTORE_DATE.tar.gz openclaw/restore-agent:/data/
kubectl exec restore-agent -n openclaw -- tar xzf /data/$RESTORE_DATE.tar.gz -C /data/

# 5. 启动 Gateway
kubectl scale deployment openclaw-gateway --replicas=1 -n openclaw

echo "✅ 恢复完成：$RESTORE_DATE"

八、最佳实践总结

8.1 配置管理

  1. 使用 ConfigMap 管理环境变量，避免硬编码
  2. 敏感信息使用 Secret，不要明文存储
  3. 配置文件外部化，便于热更新
  4. 版本化配置，记录每次变更

8.2 存储设计

  1. 单 PVC + subPath 优于多 PVC（减少挂载失败风险）
  2. 使用 ReadWriteMany 访问模式（支持多 Pod 共享）
  3. 定期清理日志，避免存储爆炸
  4. 备份策略：3-2-1 原则（3 份副本、2 种介质、1 份异地）

8.3 网络配置

  1. NodePort 适合内部访问，LoadBalancer 适合外部访问
  2. 配置网络策略，限制 Pod 间通信
  3. 使用 Service Mesh（如 Istio）进行流量管理

8.4 安全加固

  1. 最小权限原则：ServiceAccount 只授予必要权限
  2. 镜像签名验证：防止恶意镜像
  3. 网络隔离：使用 NetworkPolicy 限制访问
  4. 定期更新：及时修复安全漏洞

8.5 监控告警

  1. 定义 SLO：明确服务等级目标
  2. 多层次监控：基础设施 + 应用 + 业务
  3. 智能告警：避免告警疲劳
  4. 自动化恢复：尽可能自愈

九、未来规划

9.1 短期优化（1-3 个月）

  • 实现配置热更新（无需重启 Pod）
  • 添加 HPA（水平自动扩缩容）
  • 集成分布式追踪（Jaeger/Zipkin）
  • 优化启动速度（目标：< 30s）

9.2 中期规划（3-6 个月）

  • 多实例部署（高可用架构）
  • 跨区域容灾
  • 自动化备份验证
  • 性能基准测试框架

9.3 长期愿景（6-12 个月）

  • Serverless 部署方案
  • 边缘计算支持
  • 多租户隔离
  • AI 驱动的自动优化

十、参考资料

10.1 官方文档

10.2 部署文件

所有部署文件已开源：

1
2
3
4
5
6
7
8
9
workspace/projects/openclaw-extension/docs/k8s-deployment/
├── 03-pvc.yaml
├── 04-serviceaccount.yaml
├── 05-configmap.yaml
├── 06-deployment.yaml
├── 07-service.yaml
├── 10-deploy.sh
├── DEPLOYMENT_PRACTICE.md
└── openclaw.json.template

10.3 相关工具

附录：完整部署清单

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# 一键部署检查清单
echo "📋 OpenClaw K8s 部署检查清单"
echo ""
echo "前置条件:"
echo "  [ ] K8s 集群可用 (kubectl cluster-info)"
echo "  [ ] CephFS StorageClass 存在 (kubectl get sc)"
echo "  [ ] Harbor 镜像可访问 (docker pull hb.test/...)"
echo "  [ ] DashScope API Key 有效"
echo ""
echo "部署步骤:"
echo "  [ ] 创建命名空间"
echo "  [ ] 应用 PVC"
echo "  [ ] 应用 RBAC"
echo "  [ ] 应用 ConfigMap"
echo "  [ ] 应用 Deployment"
echo "  [ ] 应用 Service"
echo "  [ ] 验证 Pod 状态"
echo "  [ ] 验证服务访问"
echo ""
echo "验证测试:"
echo "  [ ] WebSocket 连接测试"
echo "  [ ] 模型调用测试"
echo "  [ ] 文件读写测试"
echo "  [ ] 日志收集测试"
echo ""

作者：John
职位：高级技术架构师
日期：2026-03-09
版本：v1.0

本文基于真实项目经验编写，所有配置和脚本均经过生产环境验证。如有问题，欢迎在评论区讨论。

架构师点评

本文适合以下团队与场景：

  • 基础设施已经 K8s 化
  • 需要把 OpenClaw 作为团队级/企业级服务部署
  • 对可用性、可观测性有一定要求

在以下场景下建议更保守：

  • 团队尚未完全熟悉 K8s
  • 仅为单用户/小团队使用，单机部署可能更简单

企业落地建议

  1. 先做最小可行部署，验证核心场景后再逐步复杂：
    • 先跑通单 Pod 无状态部署
    • 再逐步增加持久化、Ingress、监控等
  2. 重视安全与权限：
    • 把 API 密钥、敏感配置放到 Secret
    • 不要用 root 权限运行容器
    • 严格控制网络访问范围
  3. 配套可观测性与运维保障：
    • 至少要有基本的日志收集与告警
    • 配置合理的资源限制与健康检查
    • 准备简单的重启/升级/回滚预案
  4. 从“部署起来”到“生产可用”再到“规模化落地”：
    • 先稳定运行 1-2 周，观察稳定性
    • 再逐步接入内部系统、更多技能/插件
    • 最后考虑多租户、高可用等

相关资源