1. 项目概述为什么需要一个“永不关机”的远程开发代理作为一名常年与代码打交道的开发者我经常遇到一个尴尬的场景本地电脑上跑着一个耗时漫长的构建、测试或者数据同步任务而我却不得不合上笔记本去开会、通勤或者干脆想让它休息一下。一旦断开连接所有进程中断前功尽弃。更别提那些对算力有要求的任务本地风扇狂转机器烫得能煎鸡蛋。这就是vps-agent项目要解决的核心痛点将你的开发环境特别是AI辅助编程的“大脑”——Cursor Agent部署到一台远程的VPS虚拟专用服务器上让它24/7不间断运行。你可以在本地通过SSH连接上去在一个持久的tmux会话中工作然后随时安全地断开连接。你的代码、终端状态、正在运行的进程全部原封不动地保留在云端。等你需要时再重新连接就像从未离开过一样。这不仅仅是“远程桌面”那么简单。它通过Ansible实现了自动化部署确保环境的一致性和可重复性通过tmux提供了强大的终端会话管理能力而核心是集成了Cursor Agent CLI让你能在云端享受AI结对编程的便利同时释放本地资源。简单来说它为你构建了一个专属的、永不离线的云端开发工作站。2. 核心思路与工具选型解析2.1 为什么是这套技术栈这个项目的设计非常精炼每个工具的选择都直指核心需求没有一丝冗余。我们来拆解一下Ansible作为自动化配置管理工具它是这个项目的基石。它的优势在于“声明式”和“无代理”。我们只需要用YAML语言描述最终的系统状态“需要安装tmux”、“需要创建cursor用户”Ansible会自行判断如何达到这个状态。相比需要在中控机和目标机都安装客户端的方案Ansible仅需通过SSH连接大大简化了部署流程。这对于管理单台或多台VPS来说是最清晰、最可维护的选择。Ubuntu 24.04 LTS on ARM64选择最新的LTS版本确保了长期稳定的系统支持和软件包更新。而指定ARM64架构则是一个充满前瞻性的选择。目前各大云服务商如AWS的Graviton、Azure的Ampere提供的ARM实例在同等性能下价格通常比x86实例低20%-40%性价比极高。对于运行开发环境、编译等任务ARM64已具备完善的生态支持。Tmux这是实现“持久会话”能力的灵魂。Tmux是一个终端复用器它允许你在一个终端窗口中创建多个“窗格”Pane和“窗口”Window更重要的是这些会话可以脱离当前SSH连接而独立存在。你detach分离后所有进程照常运行你换个时间、换个网络attach附加回来一切如初。它比screen更现代功能更强大是运维和开发者的标配。Cursor Agent CLI这是项目的价值核心。Cursor是一款深度集成AI的IDE其Agent功能能理解上下文、自动补全、甚至编写代码。将其CLI版本部署在云端意味着你可以获得一个不知疲倦、算力充沛的云端编程伙伴。无论是代码生成、重构建议还是错误排查它都能在后台持续为你服务。Taskfile这是一个常常被忽略但极大地提升了项目易用性的工具。它用简单的YAML文件定义了一系列任务Task比如“部署”、“连接”、“更新”。用户不需要记忆复杂的Ansible命令只需要运行task deploy或task connect即可。它统一了项目入口降低了使用门槛。这套组合拳下来实现了一个优雅的闭环用Ansible一键搭建环境用Tmux维持工作状态用Cursor Agent提升效率最后用Taskfile简化所有操作。2.2 与官方方案的对比思考项目文档中提到了Cursor官方的“自托管云代理”和“Agent Client Protocol (ACP)”。为什么还要自己造轮子这恰恰体现了实践者的智慧。官方自托管代理Undercooked正如文档所说截至2026年4月该功能可能还不完善存在如“无法自动补全文件”等基础功能缺失的问题。依赖一个尚在雏形的功能对于生产性或严肃的开发工作流来说风险太高。自己搭建的方案可控性更强功能也更完整。ACP协议Work in Progress新的协议标准意味着未来的可能性但也意味着当前的不稳定性和兼容性问题。vps-agent基于成熟的SSH和Tmux技术栈稳定可靠几乎不存在兼容性风险并且其模式持久终端会话是通用的不局限于Cursor你可以在这个环境里运行任何CLI工具。因此vps-agent的定位非常清晰它是一个基于成熟、稳定技术构建的立即可用、高度可控的云端开发环境解决方案完美填补了官方方案成熟前的空白。3. 前期准备与详细配置指南3.1 本地环境准备你的笔记本电脑在开始向云端部署之前我们需要在本地配置好“发射台”。安装Taskfile这是我们的指挥中心。访问 taskfile.dev 选择适合你操作系统macOS, Linux, Windows的安装方式。通常macOS用户用brew install go-task/tap/go-taskLinux用户可以直接下载二进制文件。安装后在终端运行task --version确认安装成功。安装Ansible与Ansible-lint项目推荐使用uv这个现代的Python包管理工具来安装这能有效避免污染系统全局Python环境。# 安装uv如果尚未安装 curl -LsSf https://astral.sh/uv/install.sh | sh # 使用uv安装ansible-core和ansible-lint uv tool install ansible-core uv tool install ansible-lint注意使用uv安装后你可能需要将uv的bin目录通常是~/.local/bin添加到你的PATH环境变量中或者通过uv run ansible-playbook来运行命令。更通用的方式是使用uv创建的虚拟环境。不过对于这个一次性安装的系统工具用系统包管理器如brew install ansible或apt install ansible可能更直接。uv的优势在于版本隔离。安装并认证GitHub CLI (gh)安装访问 cli.github.com 按指南安装。认证这是关键一步。运行gh auth login按照提示选择GitHub.com推荐使用SSH密钥认证方式这与后续Ansible操作匹配。完成后务必运行gh auth status确认显示登录成功。Ansible剧本会调用gh命令来管理部署密钥所以这步必须提前做好。3.2 准备你的云端战场VPS你需要一台运行Ubuntu 24.04 ARM64的VPS。几乎所有主流云厂商都提供此类服务AWS EC2选择t4g或m6g等Graviton系列实例ARM64在创建实例时选择Ubuntu 24.04 LTS AMI。DigitalOcean创建Droplet时在“镜像”中选择Ubuntu 24.04 LTS在“CPU选项”中勾选“Premium Intel AMD”或专门筛选ARM机型。Linode创建实例时选择“Distributions”下的Ubuntu 24.04 LTS并选择ARM64架构的机型。Vultr在部署服务器时选择“Cloud Compute”或“Optimized Cloud Compute”应用选择Ubuntu 24.04服务器类型选择“Ampere (ARM)”系列。创建VPS时的关键操作区域选择尽量选择离你物理位置近的区域以降低SSH延迟。SSH密钥对在创建实例时务必上传你的本地公钥通常是~/.ssh/id_ed25519.pub或~/.ssh/id_rsa.pub。这是你免密登录的凭证。云服务商会将公钥自动注入到新服务器的authorized_keys文件中。安全组/防火墙确保开放22端口SSH。其他端口暂时不需要。获取你的VPS的公网IP地址。3.3 配置Ansible库存清单这是连接本地和云端的桥梁。项目结构已经规划好你只需要填写信息。克隆项目仓库git clone https://github.com/meoyawn/vps-agent.git cd vps-agent复制并编辑库存文件cp ansible/inventory/hosts.example.yaml ansible/inventory/hosts.yaml用你喜欢的编辑器打开ansible/inventory/hosts.yaml。它的内容类似于all: children: vps: # 这个组名必须是 vps因为Playbook只针对这个组执行 hosts: your_vps_hostname: # 这里可以是你自定义的主机名如 my-dev-agent ansible_host: 203.0.113.10 # 替换成你的VPS公网IP ansible_user: ubuntu # 通常是Ubuntu镜像的默认用户名 # ansible_ssh_private_key_file: ~/.ssh/id_ed25519 # 如果你的密钥不是默认路径或名称需取消注释并指定ansible_host: 填入你的VPS IP地址。ansible_user: Ubuntu云镜像的默认用户通常是ubuntu。如果你用的其他发行版或自定义镜像请更改。ansible_ssh_private_key_file: 如果你使用的SSH私钥不是默认的例如你为这个项目专门生成了新密钥对或者密钥放在非标准路径需要取消注释这行并指定正确的路径。4. 一键部署与核心工作流实操4.1 执行自动化部署当你的hosts.yaml配置无误后部署就变得极其简单。在项目根目录下运行task apply这个命令背后Taskfile.yml定义了一个名为apply的任务它实际上执行了ansible-playbook ansible/playbooks/site.yaml。让我们深入看看这个Playbook (site.yaml) 做了哪些了不起的事情系统基础配置更新apt缓存安装基础工具包如vim,git,curl,wget等。创建专用用户创建一个名为cursor的系统用户并为其配置sudo权限无需密码后续所有操作都在此用户下进行实现环境隔离。配置SSH与GitHub密钥在VPS上为cursor用户生成一对新的SSH密钥。利用你本地已经认证好的ghCLI将生成的公钥自动注册到你的GitHub账户作为“部署密钥”。这意味着cursor用户可以直接克隆你的私有仓库无需额外配置令牌。重要提示这个过程需要你的GitHub账户有相应的权限添加SSH密钥。确保gh auth status输出正确。安装核心软件Tmux安装并配置基础设置。Cursor Agent CLI从Cursor官方下载最新的CLI二进制文件安装到cursor用户的目录下并确保其在PATH中。创建工作区目录在cursor用户的家目录下创建~/workspace/目录作为所有代码仓库的统一存放点。整个过程完全自动化你只需要在初始时输入一次VPS的IP地址。部署成功后你的云端开发环境就准备就绪了。4.2 日常使用工作流部署完成后日常使用才是精髓所在。你不再需要记住复杂的SSH命令。连接到你的云端工作会话 在本地终端只需运行task tmux这个命令会通过SSH连接到你的VPS。切换到cursor用户。检查是否存在名为cursor的tmux会话默认名称如果不存在则创建它。将你的本地终端附加attach到这个会话上。此刻你的终端已经“进入”了VPS上的那个持久会话。你可以在这里运行任何命令。在会话中开始工作# 进入预设的工作区 cd ~/workspace # 克隆你的项目 git clone gitgithub.com:yourname/yourproject.git cd yourproject # 启动Cursor Agent让它分析这个项目 cursor-agent # 现在你可以像在本地一样使用Cursor的AI功能了 # 例如让Agent帮你写一个函数或者解释一段代码cursor-agent启动后通常会运行在后台或占用当前终端。你可以使用CtrlB然后按D来分离detach当前tmux会话。注意这只是从会话中分离cursor-agent进程和所有其他命令仍在VPS上继续运行。Tmux基本操作指南 在tmux会话中所有命令都以前缀键开始默认是CtrlB。CtrlB D分离当前会话会话在后台运行。CtrlB C在当前会话中创建一个新窗口Window。CtrlB ,重命名当前窗口。CtrlB 数字切换到指定编号的窗口。CtrlB %将当前窗格垂直分割。CtrlB 将当前窗格水平分割。CtrlB 方向键在窗格间切换焦点。CtrlB Z将当前窗格全屏放大再按一次恢复。在终端中直接运行tmux attach -t cursor可以重新附加到名为cursor的会话。断开与重连 当你需要离开时在tmux会话中按下CtrlB D即可分离。然后直接关闭本地终端窗口。 任何时候你想回来只需在本地再次运行task tmux你就会回到离开时的精确状态——光标位置、命令历史、正在运行的后台进程如cursor-agent一切如常。4.3 维护与更新环境需要维护vps-agent也提供了便捷的方式。更新Cursor AgentCursor Agent CLI会频繁更新以获取新功能。要更新VPS上的Agent只需在本地运行task update-cursor-agent这个任务会运行一个独立的Playbook专门用于下载并替换VPS上cursor用户目录下的Agent二进制文件。修改配置或增删软件如果你需要调整VPS上的配置例如安装额外的系统包、修改tmux配置、添加环境变量你应该去修改ansible/playbooks/目录下的对应Playbook或角色Role文件然后再次运行task apply。Ansible具有幂等性这意味着多次运行同一个Playbook是安全的它只会让系统达到Playbook描述的状态而不会造成重复操作或错误。5. 深度优化、问题排查与安全实践5.1 性能与使用优化技巧SSH连接优化编辑本地的~/.ssh/config文件为你的VPS添加配置可以显著提升连接速度和稳定性。Host my-dev-agent # 与你 inventory 中设置的主机名一致 HostName 203.0.113.10 User cursor # 连接时直接使用 cursor 用户 IdentityFile ~/.ssh/id_ed25519 # 指定私钥 ServerAliveInterval 60 # 每60秒发送一个保活包防止连接超时 ServerAliveCountMax 3 TCPKeepAlive yes Compression yes # 启用压缩加速传输配置后你可以直接用ssh my-dev-agent连接task tmux命令内部的SSH调用也会受益于这些优化参数。Tmux配置美化与增强默认的tmux配置比较简陋。你可以为cursor用户创建~/.tmux.conf文件来增强体验。例如将前缀键从CtrlB改为更顺手的CtrlA需注意不要与终端跳转行首快捷键冲突# 更改前缀键 unbind C-b set -g prefix C-a bind C-a send-prefix # 启用鼠标支持方便调整窗格大小、选择窗格 set -g mouse on # 设置状态栏更美观 set -g status-style bgblack,fgwhite set -g window-status-current-style bgred,fgblack # 设置窗格边框颜色 set -g pane-border-style fggreen set -g pane-active-border-style fgbrightred # 重新加载配置文件的快捷键修改后按前缀R生效 bind R source-file ~/.tmux.conf \; display-message Config reloaded.将这些配置通过Ansible自动化部署是更好的实践你可以将其添加到Playbook中实现一键配置。工作区管理养成在~/workspace下按项目克隆仓库的习惯。你可以在tmux中为每个项目创建一个独立的窗口Window并重命名窗口以便识别。例如窗口1叫“backend”窗口2叫“frontend”。5.2 常见问题与故障排除即使自动化程度很高也可能会遇到问题。下面是一个快速排查指南问题现象可能原因解决方案运行task apply失败提示“SSH连接被拒绝”或“认证失败”。1. VPS IP地址错误。2. 安全组未开放22端口。3. 本地私钥路径错误或权限不对。4. VPS上的默认用户名不是ubuntu。1. 核对hosts.yaml中的ansible_host。2. 登录云控制台检查防火墙/安全组规则。3. 检查ansible_ssh_private_key_file路径并确保私钥文件权限为600 (chmod 600 ~/.ssh/id_xxx)。4. 尝试用ssh ubuntuip手动连接确认用户名。task apply在“注册GitHub SSH密钥”步骤失败。1. 本地ghCLI未登录 (gh auth status失败)。2. GitHub账户权限问题如启用了2FA但未配置SSH密钥的特定流程。1. 运行gh auth login重新登录。2. 尝试手动处理登录VPS (ssh cursorip)查看/home/cursor/.ssh/id_ed25519.pub将其内容复制并手动添加到GitHub的SSH Keys设置中。运行task tmux提示“找不到会话cursor”或无法附加。Tmux会话尚未创建或者会话名不是cursor。首次运行task tmux时会自动创建。如果失败可以手动SSH到VPS切换到cursor用户运行tmux new -s cursor创建会话。在tmux会话中网络断开后重连发现会话不见了。Tmux服务器可能意外终止了如VPS重启。Tmux会话默认保存在内存中服务器退出会话即丢失。这是tmux的局限。可以考虑使用tmux-resurrect或tmux-continuum插件来定期自动保存和恢复会话状态。更根本的解决方案是确保VPS稳定运行或编写系统服务来保证tmux在启动时运行。cursor-agent命令未找到或启动失败。1. Playbook安装Agent失败。2. Agent二进制文件路径未加入cursor用户的PATH。1. 运行task update-cursor-agent尝试重新安装。2. 登录VPS检查/home/cursor/.local/bin目录是否存在且包含cursor-agent文件并检查~/.bashrc或~/.profile中是否将该路径加入了PATH。感觉Agent响应慢。1. VPS配置过低CPU/内存不足。2. VPS地理位置离你太远网络延迟高。3. Agent在处理大型项目。1. 考虑升级VPS配置。2. 选择离你更近的云区域。3. 在项目根目录创建.cursorignore文件忽略node_modules,build,.git等不需要Agent分析的大目录。5.3 安全加固建议将开发环境放在公网VPS上安全至关重要。禁用密码登录仅使用SSH密钥这应该是在创建VPS时云厂商的默认选项但请再次确认。检查VPS上的/etc/ssh/sshd_config确保PasswordAuthentication设置为no。更改SSH端口将默认的22端口改为一个非标准的高位端口如2222可以避免绝大部分自动化扫描攻击。需要在sshd_config中修改Port并在云服务商的安全组中开放对应端口。使用Fail2ban安装并配置Fail2ban自动屏蔽多次尝试SSH登录失败的IP地址。定期更新系统通过Ansible Playbook加入定期执行apt update apt upgrade -y的任务或直接在VPS上配置无人值守更新。限制cursor用户的权限虽然为了方便给了sudo权限但在生产使用中可以考虑更精细的权限控制或者只授予执行特定命令如安装特定软件包的sudo权限。备份重要数据~/workspace下的代码应通过git推送到远程仓库进行备份。对于tmux会话状态等如果非常重要可以考虑定期备份tmux的resurrect脚本文件。6. 扩展场景与进阶玩法vps-agent的基础框架非常稳固你可以基于它拓展出更多强大的工作流。多项目并行开发在一个tmux会话中创建多个窗口每个窗口对应一个不同的项目目录。你可以让一个窗口运行前端开发服务器另一个窗口运行后端API第三个窗口运行数据库或消息队列。所有服务都在云端持续运行你只需一个连接即可查看所有状态。作为CI/CD的轻量级运行器你可以在VPS上安装Docker、Node.js、Python、Go等工具链。然后将这个小型的“云端开发机”作为你个人或小团队的简易CI/CD环境。通过编写脚本在tmux会话中自动运行测试、构建和部署任务。数据抓取与处理任务有些爬虫或数据处理脚本需要长时间运行。你可以将其放在这个VPS的tmux会话中让它7x24小时工作完全不影响本地电脑。学习与实验沙盒这是一个完美的实验环境。想尝试一个可能搞乱系统的新技术、新数据库在VPS上随便折腾玩坏了直接通过Ansible一键重置或者销毁VPS重开一个完全不影响主力机。集成其他CLI AI工具这个环境不限于Cursor Agent。你可以同样方式安装并运行GitHub Copilot CLI (gh copilot),Claude CLI, 或是开源的Continue等任何命令行AI工具打造一个属于你自己的云端AI助手集群。我个人最深刻的体会是这个方案带来的最大价值是“心流”的延续。以前下班时不得不中断一个复杂的调试过程第二天回来又要花大量时间重新进入状态。现在我只需要在办公室的电脑上CtrlB D回到家后task tmux所有的终端历史、未完成的命令、正在运行的本地服务器都瞬间呈现思维的上下文无缝切换。它不仅仅是一个工具更是一种让工作流适应人而非让人适应工作流的方式。从按下task apply那一刻起你就拥有了一个在云端永不停歇的数字分身。