dotfiles/MIGRATION_GUIDE.md

Dotfiles 迁移指南

个人备份说明 - 用于新机器配置参考

创建时间: 2026-03-04 适用场景: 离职后新公司机器配置

---

📋 目录

1. 备份内容
2. 不包含的内容
3. 新机器配置步骤
4. 常见问题
5. 个性化配置

---

📦 备份内容

已备份到 Git 仓库

文件/目录	说明	用途
.zshrc	Shell 配置	60+ alias 和函数
.tmux.conf	Tmux 配置	终端复用
git/config	Git 配置模板	全局 Git 设置（占位符）
nvim/	Neovim 配置	编辑器配置
wezterm/	WezTerm 配置	终端模拟器
alacritty/	Alacritty 配置	备用终端
ghostty/	Ghostty 配置	现代终端
starship.toml	Starship 配置	Shell 提示符
Brewfile	Homebrew 包列表	所有工具和应用
setup.sh	安装脚本	一键配置
ssh/example	SSH 配置模板	初始化 ~/.ssh/config
CHECKLIST.md	检查清单	配置验证
QUICKSTART.md	快速开始	3-5 分钟配置
README.md	完整文档	使用说明

.gitignore 排除规则

以下敏感数据不会被提交，需要在新机器重新配置：

.ssh/              # SSH 密钥
.1password/        # 1Password 配置
.kube/             # Kubernetes 配置
*.env              # 环境变量
credentials.json   # 凭据文件
secrets.txt        # 密钥文件

---

🚫 不包含的内容

以下数据需要手动迁移或重新配置：

需要重新生成的

• SSH 密钥对 (~/.ssh/id_ed25519)
• GPG 密钥（如果使用）
• Git 签名密钥

需要重新配置的

• Git 用户信息 (name, email)
• 1Password SSH Agent
• Kubeconfig (工作集群配置)
• SSH config 中的自定义主机条目（如需额外调整）

需要单独备份的

• 浏览器书签
• 应用许可证
• 其他个人数据

---

🚀 新机器配置步骤

步骤 1: 克隆仓库

git clone <your-repo-url> ~/.dotfiles
cd ~/.dotfiles

步骤 2: 运行一键恢复

./setup.sh full-recover

这将自动完成：

• ✅ Xcode Command Line Tools 安装
• ✅ Homebrew 安装
• ✅ zsh antigen 安装
• ✅ asdf 版本管理器安装
• ✅ dotfiles 软链接创建
• ✅ 如 ~/.ssh/config 不存在，则用模板初始化
• ✅ Git 基础配置
• ✅ fzf 安装

步骤 3: 配置个人信息

Git 配置

# 替换为你的真实信息
git config --file ~/.gitconfig user.name "Your Name"
git config --file ~/.gitconfig user.email "your@email.com"
git config --file ~/.gitconfig user.signingkey "your-ssh-public-key"

SSH 密钥生成

# 生成新密钥
ssh-keygen -t ed25519 -C "your@email.com"

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

# 添加到 GitHub/GitLab
# 1. 复制公钥: cat ~/.ssh/id_ed25519.pub | pbcopy
# 2. 粘贴到 GitHub: Settings → SSH and GPG keys → New SSH key

1Password SSH Agent (如果使用)

# 如果 install 没自动创建，再手动创建符号链接
mkdir -p ~/.1password
ln -s ~/Library/Group\ Containers/2BUA8C4S2C.com.1password/t/agent.sock ~/.1password/agent.sock

# 添加 SSH 密钥到 1Password
op ssh add ~/.ssh/id_ed25519

步骤 4: 安装 Homebrew 包

# 安装所有包和应用
brew bundle install

这会安装：

• CLI 工具 (bat, ripgrep, fzf, lsd, difftastic)
• 开发语言 (go, rustup, node, lua, bun, uv)
• 数据库 (mysql, postgresql, redis)
• Mac 应用 (1Password, Ghostty, Cursor, Obsidian, etc.)
• VSCode 扩展

步骤 5: 验证安装

# 运行检查脚本
./setup.sh check

预期输出：

Homebrew: ✓ installed
Zsh: ✓ installed
Neovim: ✓ installed
Tmux: ✓ installed
Antigen: ✓ installed

步骤 6: 重启终端

# 重启终端或重新加载配置
source ~/.zshrc

---

❓ 常见问题

Q1: zsh 配置不生效

# 重新加载配置
source ~/.zshrc

# 或重启终端

Q2: Neovim 插件报错

# 同步所有插件
nvim --headless "+Lazy! sync" +qa

# 或打开 Neovim 后运行 :Lazy sync

Q3: Homebrew 权限问题

# 修复权限
sudo chown -R $(whoami) $(brew --prefix)

Q4: Git 签名失败

# 检查 1Password SSH agent
ls -la ~/.1password/agent.sock

# 列出已添加的密钥
op ssh list

# 如果没有密钥，添加它
op ssh add ~/.ssh/id_ed25519

Q5: Antigen 插件加载慢

# 更新 antigen
antigen selfupdate

# 更新所有插件
antigen update

# 清理缓存
antigen reset
antigen apply

Q6: Tmux 插件未安装

# 在 tmux 中按下 Ctrl-a + I (大写的 i)
# 这会安装 TPM 插件

---

⚙️ 个性化配置

修改 Git 配置

仓库中的 git/config 只作为模板使用。机器上的实际配置请直接修改 ~/.gitconfig：

git config --global user.name "Your Name"
git config --global user.email "your@email.com"

添加新 alias

编辑 ~/.dotfiles/.zshrc，在 alias 区域添加：

alias myalias='command'

然后运行 source ~/.zshrc

添加 Homebrew 包

编辑 ~/.dotfiles/Brewfile，添加：

brew "package-name"
cask "app-name"

然后运行 brew bundle install

修改 Neovim 配置

编辑 ~/.dotfiles/nvim/lua/plugins/ 下的文件。

---

📞 需要帮助？

• 查看 README.md 获取完整文档
• 查看 CHECKLIST.md 获取检查清单
• 查看 QUICKSTART.md 获取快速开始
• 运行 ./setup.sh help 查看命令说明

---

📝 配置记录

当前配置

项目	值
Shell	zsh + antigen + oh-my-zsh
编辑器	Neovim (lazy.nvim)
终端	WezTerm / Ghostty / Alacritty
终端复用	Tmux (TPM)
提示符	Starship
版本管理	asdf

主要工具

• 语言: Go, Rust, Node.js, Python, Lua, Bun
• K8s: kubectl, k9s, helm, kubectx
• 数据库: MySQL, PostgreSQL, Redis
• Git: SSH 签名 (1Password)

---

🔐 安全提醒

1. 不要提交敏感数据 - 所有敏感路径已在 .gitignore 中排除
2. 新机器重新生成密钥 - SSH、GPG 等密钥应该在新机器重新生成
3. 移除旧机器授权 - 离职前移除旧机器的 GitHub、1Password 授权
4. 更新密码 - 如果可能，更新重要账户的密码

---

祝新工作顺利！ 🎉

---

💾 离职前备份流程

1. 运行备份脚本

cd ~/.dotfiles
./setup.sh backup

2. 备份输出说明

备份完成后会生成以下文件：

文件	内容	是否提交
Brewfile	Homebrew 包列表	✅
.git_config_summary.txt	Git 配置（包含真实信息）	⚠️ 不要
ssh_backup_YYYYMMDD_HHMMSS/	SSH 公钥	⚠️ 不要
.1password_config.txt	1Password 设置	✅
.vscode_extensions.txt	VSCode 扩展	✅
.backup_report_*.md	备份报告	✅

3. 查看备份报告

# 查看最新的备份报告
cat .backup_report_*.md | tail -50

备份报告会显示：

• ✅ 已备份的项目
• ⚠️ 未找到的配置
• 📝 下一步操作建议

4. 提交备份

# 查看变更
git status

# 提交安全文件
git add Brewfile .1password_config.txt .vscode_extensions.txt
git commit -m 'backup: pre-leaving dotfiles backup'
git push

5. 清理敏感文件

# 确认敏感文件已被 .gitignore 排除
git status --porcelain | grep -E "(summary|ssh_backup)"

# 如果没有输出，说明已正确排除

6. 额外备份建议

• 导出浏览器书签 (Chrome/Fi refox/Safari)
• 备份 1Password 紧急工具包
• 记录常用 SSH 主机配置
• 导出 Kubeconfig (如果允许)
• 备份其他应用配置 (Raycast, Obsidian 等)

---

🔐 安全提醒

不要提交的文件

以下文件包含敏感信息，已在 .gitignore 中排除：

.git_config_summary.txt    # Git 真实配置
ssh_backup_*/              # SSH 公钥
.1password_config.txt      # 1Password 配置
.backup_report_*.md        # 备份报告

离职前检查

• 移除旧机器授权: GitHub → Settings → Devices
• 移除 1Password 授权: 1Password → Settings → Security
• 更新重要账户密码
• 备份个人 SSH 公钥 (用于新机器)

---