Skip to content

MIGRATION_GUIDE.md

Latest commit

 

History

History
422 lines (302 loc) · 9.37 KB

MIGRATION_GUIDE.md

File metadata and controls

422 lines (302 loc) · 9.37 KB
Raw

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 检查清单 配置验证
pi/ Pi agent 配置 模型/主题/扩展/prompts + MCP ${VAR} 模板（凭证不入库）
scripts/pi-secrets-scan.sh 凭证守卫 提交前扫描 pi/ 是否混入密钥
scripts/pi-credential-audit.sh 价值审计 把真实密钥字面值扇描工作区/索引/全部历史，确认没有灌进去也没有弄丢
QUICKSTART.md 快速开始 3-5 分钟配置
README.md 完整文档 使用说明

.gitignore 排除规则

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

.ssh/              # SSH 密钥
.1password/        # 1Password 配置
.kube/             # Kubernetes 配置
*.env              # 环境变量
credentials.json   # 凭据文件
secrets.txt        # 密钥文件
pi/agent/auth.json                    # Pi provider API key / OAuth token
pi/agent/mcp-auth.json                # MCP OAuth token
pi/agent/antigravity-accounts.json    # Antigravity 账号 token
pi/agent/secrets.env                  # MCP ${VAR} 的真实值
pi/agent/sessions/                    # 会话记录
pi/agent/models-store.json            # 模型目录缓存

🚫 不包含的内容

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

需要重新生成的

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

需要重新配置的

  • Git 用户信息 (name, email)
  • 1Password SSH Agent
  • Kubeconfig (工作集群配置)
  • SSH config 中的自定义主机条目（如需额外调整）
  • Pi 凭证：pi /login（写入 ~/.pi/agent/auth.json）
  • Pi MCP 凭证：cp ~/.dotfiles/pi/agent/secrets.env.example ~/.pi/agent/secrets.env 后填值并 chmod 600，再 pi mcp list 验证（详见 pi/README.md）

需要单独备份的

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

🚀 新机器配置步骤

步骤 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/ 下的文件。

📞 需要帮助？

📝 配置记录

当前配置

项目 值
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 公钥 (用于新机器)