1. 项目概述一个面向AI工作流的现代化Dotfiles管理方案如果你和我一样常年泡在终端里那么你的$HOME目录下一定散落着各种以点号开头的配置文件.zshrc,.tmux.conf,.config/nvim/…… 这些“点文件”定义了你的整个开发环境。管理它们曾经是个噩梦——手动复制、版本混乱、在多台机器间同步时秘密信息泄露。更别提现在AI编码助手如 Cursor、Claude Codex已成为工作流的核心它们的配置MCP 服务器、技能、API密钥同样需要被安全、一致地管理。我维护的jesuserro/dotfiles项目就是为解决这些问题而生的。它不是一个简单的配置文件合集而是一套工程化的、面向AI时代的Dotfiles管理框架。这套框架的核心是“分而治之”与“秘密隔离”。我用rcm管理传统的 shell、终端和编辑器配置Zsh, TMUX, Neovim确保基础环境轻量且高效同时我引入chezmoi作为更强大的配置管理引擎专门负责管理包含敏感信息的AI工作站AI Workstation配置例如 Cursor 和 Codex 的 MCP 设置并借助SOPS与Age对秘密信息进行加密存储实现配置的版本化与安全共享。简单来说这个项目能帮你一键搭建一个高度定制化、生产力拉满的 Linux 终端环境安全、自动化地配置你的 AI 编码助手使其具备连接数据库、操作云存储等“超能力”并通过一套清晰的协作规则让你在多台设备间无缝切换或与团队安全地共享环境配置。无论你是想彻底整顿自己混乱的 dotfiles还是希望为团队构建一个标准化的、集成了AI能力的开发环境起点这个项目都提供了经过实战检验的蓝图。2. 架构设计与核心工具选型解析为什么是rcmchezmoi的组合而不是只用其中一个这是整个项目设计的基石理解这一点你就能明白后续所有操作的意图。2.1 工具职责划分清晰边界带来维护便利我的核心设计原则是按配置的敏感性和动态性进行分层管理。RCM轻量级符号链接管家rcm是一个极简的工具集核心命令是rcup。它的工作方式非常直观在你存放 dotfiles 的仓库目录里所有以点号开头的文件或目录例如zsh/.zshrcrcup会在你的家目录$HOME中创建对应的符号链接例如~/.zshrc - ~/dotfiles/zsh/.zshrc。它管理什么静态的、非敏感的、纯本地的配置文件。在我的项目中就是zsh/,tmux/,vim/目录下的所有配置。这些配置通常不包含密码、密钥且一旦设定不会频繁变动结构。优点简单、透明、无状态。你可以直接编辑仓库里的文件rcup -v一下链接就更新了。想要回滚用git checkout即可。Chezmoi强大的模板化配置引擎chezmoi则强大得多。它不仅仅创建链接它支持模板渲染使用 Go 的text/template、条件逻辑针对不同操作系统、主机名应用不同配置、以及对加密数据的原生支持。它管理什么动态的、包含秘密的、或需要根据上下文生成的配置。在我的项目中dot_cursor/,dot_codex/,ai/以及最重要的secrets.sops.yaml都由chezmoi管理。dot_前缀是chezmoi的约定表示这些目录中的文件将被管理并放置到目标位置去掉dot_前缀。核心价值安全地管理秘密。我可以将加密后的 API 令牌、数据库连接字符串写在模板里chezmoi apply时配合SOPS它会自动解密并渲染到正确的文件位置而我的 Git 仓库中存储的始终是加密后的密文。2.2 秘密管理SOPS 与 Age 的黄金组合这是项目安全性的核心。传统的做法是将秘密放在.env文件里并加入.gitignore但这不利于团队协作和环境复现。SOPS全称 “Secrets OPerationS”它本身不加密数据而是像一个“加密信封”可以封装 YAML、JSON、ENV 等格式的文件并支持多种加密后端如 AWS KMS, GCP KMS, Age, PGP。Age一个简单、现代、高效的加密工具。我选择它作为 SOPS 的后端因为它无需复杂的密钥管理基础设施如 GPG只需一个或多个本地的 age 公钥/私钥对。工作流我在本地生成一个 age 密钥对age-keygen -o key.txt。在~/.config/sops/.sops.yaml中配置 SOPS指定使用我的 age 公钥进行加密。当我需要添加一个秘密时我编辑secrets.sops.yaml文件。SOPS 会自动调用 age 用我的公钥加密新增的内容。执行chezmoi apply时chezmoi会调用 SOPS 解密该文件并将解密后的值填充到对应的配置模板中例如将GITHUB_TOKEN填入dot_cursor/mcp.json.tmpl。加密后的secrets.sops.yaml可以安全地提交到 Git 仓库。只有拥有对应 age 私钥的人或机器才能解密和应用这些配置。2.3 AI工作站框架让AI助手真正融入工作流“AI Workstation” 是这个项目区别于传统 dotfiles 的亮点。它主要围绕Model Context Protocol展开。MCP 是什么你可以把它理解为 AI 助手如 Cursor、Claude Desktop的“插件协议”或“驱动协议”。一个 MCP 服务器Server为 AI 客户端Client提供一组特定的“工具”或“技能”。项目中的实现ai/目录下定义了一系列 MCP 服务器配置和技能。例如一个postgres.mcp.json可能配置了一个连接到本地 PostgreSQL 数据库的 MCP 服务器。dot_cursor/mcp.json.tmpl是一个chezmoi模板它会在应用时动态地将所有启用的 MCP 服务器配置整合到 Cursor IDE 的最终mcp.json配置文件中。带来的能力配置好后你可以在 Cursor 里直接对 AI 说“查询一下用户表里最近注册的10个人”AI 会通过配置好的 PostgreSQL MCP 服务器执行查询并返回结果。这极大地扩展了 AI 助手处理实际任务的能力边界。注意初次接触 MCP 可能会觉得抽象。你可以简单理解为我们不是在配置 AI 模型本身而是在为 AI 助手这个“大脑”安装“手”和“眼睛”各种 MCP 服务器让它能操作数据库、读写文件、调用 API。3. 初始化安装与环境配置全流程假设你在一台全新的 Ubuntu 22.04 系统上让我们从头开始搭建这套环境。这个过程看似步骤不少但绝大多数都是一次性的初始化操作。3.1 前置依赖安装首先我们需要安装一些基础工具和chezmoi、rcm本身。# 更新系统包索引 sudo apt update sudo apt upgrade -y # 安装基础编译工具和 Git sudo apt install -y build-essential git curl wget # 安装 Zsh如果你不是用它后续配置需要调整 sudo apt install -y zsh # 安装 Age用于加密 # 从 GitHub 发布页下载最新的 .deb 包请替换 X.Y.Z 为实际版本号 wget https://github.com/FiloSottile/age/releases/download/vX.Y.Z/age_X.Y.Z_linux_amd64.deb sudo dpkg -i age_X.Y.Z_linux_amd64.deb # 安装 SOPS同样从发布页下载 wget https://github.com/getsops/sops/releases/download/vX.Y.Z/sops_X.Y.Z_linux.amd64.deb sudo dpkg -i sops_X.Y.Z_linux.amd64.deb # 安装 Chezmoi推荐使用官方一键脚本 sh -c $(curl -fsLS get.chezmoi.io) -- init --apply jesuserro/dotfiles # 但根据项目文档我们采用克隆仓库的方式所以这里我们先不执行上述命令而是先安装 chezmoi 二进制 curl -sfL https://git.io/chezmoi | sudo sh -s -- -b /usr/local/bin # 安装 RCM在 Ubuntu 上可以通过 PPA sudo apt-add-repository -y ppa:martin-frost/thoughtbot-rcm sudo apt update sudo apt install -y rcm3.2 克隆仓库与核心密钥配置接下来是关键的安全初始化步骤配置 Age 密钥。# 1. 克隆 dotfiles 仓库 git clone https://github.com/jesuserro/dotfiles.git ~/dotfiles cd ~/dotfiles # 2. 生成你的 Age 密钥对如果你还没有 # 这会在当前目录生成 key.txt私钥和输出公钥。私钥是你的命根子绝不能泄露或提交 age-keygen -o key.txt # 命令会输出你的公钥形如age1xxxx...。复制它。 # 3. 配置 SOPS 使用你的 Age 公钥 # 创建 SOPS 配置目录和文件 mkdir -p ~/.config/sops cat ~/.config/sops/.sops.yaml EOF creation_rules: - age: - YOUR_AGE_PUBLIC_KEY_HERE # 请替换为上一步复制的公钥 EOF # 使用文本编辑器如 nano将 YOUR_AGE_PUBLIC_KEY_HERE 替换为你的公钥字符串。 nano ~/.config/sops/.sops.yaml # 4. 重要安全备份你的 Age 私钥 # 将 key.txt 移动到安全的地方比如密码管理器或加密的 USB 驱动器。 # 并从当前目录删除它防止误提交。 mv key.txt ~/.config/sops/age_key.txt # 示例位置你可以自定义 chmod 600 ~/.config/sops/age_key.txt # 设置严格的权限3.3 应用配置双引擎初始化现在仓库和密钥都已就位可以应用配置了。# 1. 首先让 Chezmoi 处理需要模板和秘密的 AI 工作站配置。 # --source 参数指定仓库路径apply 命令会读取模板和加密的 secrets解密并生成最终文件到你的家目录。 chezmoi --source$HOME/dotfiles apply # 首次运行可能会提示关于 secrets 的解密确保你的 age 私钥在 SOPS 能找到的位置如上一步配置。 # 2. 然后用 RCM 链接传统的 shell/终端/编辑器配置。 # -v 是 verbose 模式会显示它创建或更新了哪些链接。 rcup -v # 你会看到类似输出symlinking ~/dotfiles/zsh/.zshrc - ~/.zshrc # 3. 最后重新加载 Zsh 配置使所有别名、函数和 PATH 变更在当前会话生效。 source ~/.zshrc如果一切顺利你的终端提示符应该已经变成了项目预设的 Zsh 主题样式例如包含 Git 分支信息并且可以尝试一些项目定义的别名比如ups。实操心得第一次运行chezmoi apply时如果遇到解密错误最常见的原因是 SOPS 找不到你的 age 私钥。检查~/.config/sops/age_key.txt是否存在且权限正确并确认~/.config/sops/.sops.yaml中的公钥配置无误。一个调试技巧是手动运行sops -d ~/dotfiles/secrets.sops.yaml看能否解密这能隔离出是 SOPS 的问题还是 Chezmoi 集成的问题。4. 日常使用与变更管理指南安装完成后日常使用主要涉及三种操作更新系统、修改配置、添加新的 MCP 或秘密。理解何时使用哪个命令至关重要。4.1 更新工作流保持环境最新项目提供了一个强大的自定义命令ups它封装了一系列更新操作。# 运行一体化更新脚本 ups这个ups命令通常是一个 shell 函数或别名定义在zsh/或aliases中可能会依次执行sudo apt update sudo apt upgrade -y更新系统包。npm update -g更新全局 npm 包。upgrade_oh_my_zsh更新 Oh My Zsh 框架及其插件。更新ai/目录下的 MCP 服务器定义或技能可能通过 git submodule 或内部脚本。关键区别运行ups后通常只需要执行source ~/.zshrc来重新加载 shell 环境因为ups可能更新了 Oh My Zsh 或相关脚本。此时不需要运行chezmoi apply因为ups并没有修改chezmoi所管理的模板源文件dot_*目录或secrets.sops.yaml。4.2 修改配置工作流区分变更类型这是最容易混淆的地方。请根据你修改的文件类型遵循下表操作你修改了…位于…工具管理需要执行的命令原因解析Zsh/Tmux/Vim 配置~/dotfiles/zsh/,tmux/,vim/RCMrcup -v source ~/.zshrcrcup更新符号链接source使 Zsh 变更生效。Cursor/Codex MCP 模板~/dotfiles/dot_cursor/,dot_codex/Chezmoichezmoi --source$HOME/dotfiles applyChezmoi 需要重新渲染模板并复制到~/.cursor/,~/.codex/。AI 技能或 MCP 定义~/dotfiles/ai/Chezmoichezmoi --source$HOME/dotfiles apply这些文件被 Chezmoi 管理并可能被模板引用。加密的秘密文件~/dotfiles/secrets.sops.yamlChezmoi SOPSchezmoi --source$HOME/dotfiles apply修改加密文件后必须用 Chezmoi 来解密和应用。本地覆盖文件~/dotfiles-local/*.localRCMrcup -v source ~/.zshrc本地文件由 RCM 的机制管理。一个典型场景你想为 Cursor 添加一个新的 MCP 服务器比如一个连接至内部文档库的服务器。你编辑~/dotfiles/dot_cursor/mcp.json.tmpl文件按照 JSON 格式添加新的服务器配置块。运行chezmoi --source$HOME/dotfiles apply。Chezmoi 会处理这个模板生成最终的~/.cursor/mcp.json文件。不需要运行rcup或source因为这只影响了 Cursor 的配置与 shell 环境无关。重启 Cursor IDE它就会读取新的mcp.json并加载新服务器。4.3 添加一个新的秘密假设你需要添加一个OPENAI_API_KEY供某个 MCP 技能使用。# 1. 使用 SOPS 编辑加密文件。SOPS 会自动用你的 age 公钥加密新内容。 sops ~/dotfiles/secrets.sops.yaml # 这会用默认编辑器如 vim打开文件。文件结构是 YAML。 # 2. 在文件中添加新的键值对。例如在适当位置添加 # cursor: # openai_api_key: sk-your-actual-openai-api-key-here # 保存并退出编辑器。SOPS 会加密你新增的 sk-... 部分。 # 3. 应用变更。Chezmoi 会解密这个文件并将 openai_api_key 的值提供给需要它的模板。 chezmoi --source$HOME/dotfiles apply # 4. 验证检查生成的配置文件例如 ~/.cursor/mcp.json中对应的 API 密钥是否已被正确填充应该是明文而非变量名。注意事项永远不要直接编辑secrets.sops.yaml的加密文本。一定要通过sops命令来编辑以保证加密的正确性。直接编辑密文会导致文件损坏无法解密。5. 高级主题自定义、调试与故障排除当你熟悉基础操作后可能会需要根据个人习惯进行调整或者解决一些遇到的问题。5.1 进行本地自定义而不污染主仓库项目通过 RCM 的“本地覆盖”机制优雅地支持这一点。任何在~/dotfiles-local/目录下以对应配置名加.local后缀命名的文件都会在rcup执行时自动被链接并覆盖主仓库中的配置。例如你想添加一个私人别名但不想提交到公共仓库# 创建本地别名文件 echo alias mysecretecho this is private ~/dotfiles-local/aliases.local # 运行 rcup它会将 aliases.local 链接为 ~/.aliases rcup -v # 重新加载 shell source ~/.zshrc # 现在 mysecret 命令就可以用了~/.aliases文件的内容将是主仓库的aliases和你本地aliases.local的合并具体行为取决于 RCM 版本和配置通常是追加或覆盖。~/dotfiles-local/目录本身应该被添加到你的全局.gitignore文件中。5.2 调试 Chezmoi 与 SOPS当chezmoi apply没有按预期工作时可以逐层排查。查看 Chezmoi 计划在执行前可以先让chezmoi告诉你它将要做什么而不实际执行。chezmoi --source$HOME/dotfiles diff这会显示它认为的目标状态和当前状态的差异。验证模板渲染你可以让chezmoi只输出它渲染后的模板内容看看变量替换是否正确。chezmoi --source$HOME/dotfiles cat ~/.cursor/mcp.json # 或者对于模板文件 chezmoi --source$HOME/dotfiles execute-template ~/dotfiles/dot_cursor/mcp.json.tmpl手动测试 SOPS 解密直接使用 SOPS 命令解密秘密文件确保加密解密本身没问题。sops -d ~/dotfiles/secrets.sops.yaml如果失败会给出明确的错误信息通常是密钥问题。5.3 常见问题与解决方案速查表问题现象可能原因解决方案运行chezmoi apply报错failed to decrypt data1. Age 私钥未找到或路径不对。2.~/.config/sops/.sops.yaml中公钥配置错误。3. 加密文件损坏。1. 检查age密钥文件路径和权限。2. 核对.sops.yaml中的公钥是否与生成密钥时的一致。3. 尝试用sops -d手动解密确认问题。运行rcup后配置未生效1. 未执行source ~/.zshrc。2. 符号链接指向错误或损坏。1. 执行source ~/.zshrc。2. 检查ls -la ~/.zshrc是否指向正确的 dotfiles 路径。添加 MCP 后 Cursor 无反应1.mcp.json语法错误。2. MCP 服务器进程未启动或崩溃。3. Cursor 未重启。1. 用 JSON 验证器检查~/.cursor/mcp.json。2. 查看 Cursor 的开发者控制台或日志。3. 完全重启 Cursor IDE。ups命令找不到source ~/.zshrc未执行或别名未正确定义。确保已执行source ~/.zshrc。检查~/dotfiles/zsh/或~/dotfiles/aliases中ups的定义。修改.local文件不生效文件未放在~/dotfiles-local/目录或文件名格式不对。确保文件路径如~/dotfiles-local/aliases.local且执行了rcup -v。5.4 项目结构深度解读理解仓库目录结构能让你更自如地导航和定制。dotfiles/ ├── ai/ # AI工作站核心 │ ├── mcp_servers/ # 各类 MCP 服务器配置定义如 postgres, minio │ ├── skills/ # 预定义的 AI 技能包 │ └── README.md # AI 框架说明 ├── dot_cursor/ # Chezmoi 管理的 Cursor 配置模板 │ └── mcp.json.tmpl # 主模板会引用 secrets 和 ai/ 中的配置 ├── dot_codex/ # Chezmoi 管理的 Claude Codex 配置模板 ├── docs/ # 完整文档遇到问题先来这里查 ├── zsh/ # RCM 管理的 Zsh 配置主题、插件、函数 ├── tmux/ # RCM 管理的 Tmux 配置 ├── vim/ # RCM 管理的 Neovim 初始化配置 ├── aliases # RCM 管理的通用别名文件 ├── secrets.sops.yaml # **加密的**所有秘密信息 └── ... (其他配置文件)核心逻辑流secrets.sops.yaml中的加密数据 ai/中的配置 dot_*/中的模板在chezmoi apply时被组合、解密、渲染最终生成~/.cursor/,~/.codex/等目录下的实际配置文件。而zsh/,tmux/等则通过rcup直接符号链接到$HOME下。6. 从使用者到贡献者理解项目工作流如果你打算基于此项目构建自己的配置或者为原项目贡献代码需要遵循其 Git 工作流。6.1 个性化分支策略不建议直接在main分支上修改。标准的做法是# 1. 克隆你自己的 fork如果你要贡献或原仓库仅个人使用 git clone your-repo-url ~/dotfiles cd ~/dotfiles # 2. 为新功能或修改创建分支 git checkout -b feat/add-new-mcp-server # 3. 进行你的修改例如编辑 dot_cursor/mcp.json.tmpl # 4. 如果你需要添加新秘密使用 sops 编辑 secrets.sops.yaml sops secrets.sops.yaml # 5. 测试你的修改 chezmoi --source$HOME/dotfiles apply # 在 Cursor 或终端中测试新功能是否工作 # 6. 提交更改。注意确保 secrets.sops.yaml 的加密状态正确。 git add . git commit -m feat: add PostgreSQL MCP server configuration # 7. 推送分支并创建 Pull Request如果是贡献或合并回你的主分支。6.2 处理秘密的协作这是团队共享配置的关键。假设你要和同事共享这个 dotfiles 仓库。导出公钥每个成员都需要生成自己的 age 密钥对并将公钥age1xxx...提供出来。配置多接收者加密修改~/.config/sops/.sops.yaml在age:后面列出所有成员的公钥。creation_rules: - age: - age1yourpublickeyabc123... age1colleaguespublickeydef456... age1anotherpublickeyghi789...重新加密现有秘密用更新后的 SOPS 配置重新加密secrets.sops.yaml文件。sops -e -i secrets.sops.yaml现在这个加密文件可以被列表中任何一个人的私钥解密。任何拥有私钥的成员运行chezmoi apply时都能成功解密并应用配置。6.3 扩展框架添加你自己的模块这套框架的威力在于其可扩展性。假设你想增加一个dot_vscode/目录来管理 VS Code 的设置。创建模板目录和文件mkdir -p ~/dotfiles/dot_vscode/User # 从你当前的 VS Code 设置复制过来并替换秘密为模板变量 cp ~/.config/Code/User/settings.json ~/dotfiles/dot_vscode/User/settings.json.tmpl编辑模板用 Chezmoi 的模板变量替换敏感信息。例如将 API 密钥替换为{{ .secret.vscode.api_key }}。在secrets.sops.yaml中添加对应的秘密sops ~/dotfiles/secrets.sops.yaml # 添加 # vscode: # api_key: your_encrypted_api_key_here测试和应用chezmoi --source$HOME/dotfiles applyChezmoi 会自动将dot_vscode/User/settings.json.tmpl渲染并放置到~/.config/Code/User/settings.json。这个过程将 VS Code 的配置也纳入了版本化、秘密安全管理的范畴。你可以用同样的方式管理任何应用的配置。经过这样一套流程的梳理和实战你的开发环境不再是一堆散落的、脆弱的配置文件而是一个可版本控制、可安全协作、可一键部署的现代化基础设施。这套dotfiles方案最深的体会是它把“配置即代码”和“秘密即代码”的理念落到了实处初期投入的学习和设置成本会在日后无数次的环境重建、设备切换和团队协作中加倍回报回来。尤其是将 AI 助手的能力通过 MCP 进行标准化扩展这不再是未来而是当下提升研发效能非常实在的一步。
