做过一次挺有代表性的部署一台老服务器账号是普通用户没有 sudo连 npm 都没有全局装过却要把一个叫 claude 的服务跑起来。这个 claude 项目不是那种一条命令就能装的单体包它依赖 Node.js 运行环境、若干 npm 包还需要常驻进程。刚拿到环境的时候我在终端里敲node -v返回 command not found敲npm -v同样提示找不到命令心里其实有点发凉。但后来冷静下来把事情拆开看发现这类“受限服务器部署”根本没那么神秘核心就一句话所有东西都装进自己的用户目录所有路径都用自己的环境变量所有进程都用普通权限能控制的守护方式跑起来。这篇文章不是某个产品的官方文档而是我从实际部署里总结出来的完整路线。你手头如果也有 claude、一个 Node.js 服务、某个 Web 应用甚至是一个 Python 写的程序只要面临同样的限制条件这套思路都能直接迁移。我会把每一步为什么这么做、命令怎么写、有哪些坑讲清楚尤其会写那些常规文档里不会告诉你的事比如没有 npm 时怎么处理依赖、没有 systemd 时怎么保活进程、端口权限不够怎么办。读完你完全可以照着在自己账号下复现一遍。1. 受限环境下的部署思路不要和系统硬刚1.1 先搞清楚“没有 sudo 和 npm”到底意味着什么很多人一看到“没有 sudo”就觉得什么都干不了其实不是。没有 sudo 只是意味着你不能动/usr、/opt、/etc这些系统目录不能安装系统级的软件包不能修改系统服务配置。但你自己的家目录是完整拥有的你能执行 shell能写文件能编译程序能监听高位端口能在用户态跑任意普通进程。这就是用户态部署的立足点。没有 npm 更是一个表面问题。npm 本质是 Node.js 发行包里自带的一个工具当系统里没有全局 npm 时你依然可以下载 Node.js 的预编译二进制包解压到自己的目录下里面的bin目录里就有 node 和 npm。也就是说npm 不是独立于 Node 之外的系统组件它是 Node 官方发行包的一部分。只要你有办法获得一份 Node.js 二进制文件npm 自然就有了。真正的难点其实在别处一是怎么在没有 root 权限的情况下获得可靠的运行时二是怎么处理项目依赖尤其是依赖里那些需要编译原生模块的包三是怎么让服务在自己退出 SSH 之后还在跑。这三件事解决掉部署就完成了一大半。我当时的做法是先做一次环境侦察把系统里有的工具、没有的工具全部列出来再决定部署路径。侦察命令无非是这几条uname -a cat /etc/os-release which curl wget tar gzip make gcc g python3 git echo $HOME df -h ./这里每一条都有意义。uname -a看内核架构比如 x86_64 还是 aarch64这个直接决定你该下载哪个平台的 Node.js 二进制包。cat /etc/os-release看发行版和版本虽然用户态部署通常不用太关心发行版但某些预编译二进制对 glibc 版本有要求提前看清楚能少走弯路。which那一条是检查你有没有下载工具、解压工具、编译工具链这决定了后面是用官方二进制包还是走源码编译。df -h是看磁盘空间有些服务器/home分区本身就很小装几个大依赖可能就爆了。侦察完我心里就有了谱。这台机器是 x86_64 架构curl 和 tar 都在gcc 和 make 也装了但 git 没装python3 在但版本比较老。这个条件已经足够走“官方二进制包 手动解压”这条路了。1.2 用户态部署的核心逻辑自包含、可回滚、不污染系统把整套运行环境放进自己的目录里本质上是构建一个自包含沙箱。这个做法的好处很直观你不需要任何系统权限就能反复折腾装坏了也不影响其他人顶多把自己目录里的文件删掉重来。具体怎么组织目录我建议从一开始就规划好不要随手乱扔。我的习惯是在家目录下面建这几个目录mkdir -p ~/runtime mkdir -p ~/claude mkdir -p ~/claude/logs mkdir -p ~/claude/data mkdir -p ~/packages~/runtime放运行时的二进制比如 Node.js 解压目录。~/claude放项目本体。~/claude/logs和~/claude/data分别放日志和运行数据。~/packages是用来存放手动下载的各种依赖包、tarball、离线缓存的地方这样将来初始化新环境时不用重新去网上找。然后就是设置环境变量。这一步非常关键我会把它写进~/.bashrc让每次登录时都能直接用export RUNTIME_HOME$HOME/runtime export NODE_HOME$RUNTIME_HOME/node export PATH$NODE_HOME/bin:$HOME/.local/bin:$PATH export NODE_PATH$NODE_HOME/lib/node_modules export NPM_CONFIG_PREFIX$HOME/.npm-global这里$HOME/.local/bin是一个用户态软件常用的安装位置很多工具支持用--prefix$HOME/.local安装到那里。提前把这个目录放进 PATH后面装一些辅助工具的时候会方便很多。PATH的顺序也有讲究用户目录的路径要放在系统路径前面这样系统里就算存在旧版本也优先用你的用户态版本。环境变量配好之后再用source ~/.bashrc让它生效。下次再登录这些命令就不用手动敲一遍了。2. 获取 Node.js 运行时不靠 sudo不靠 npm2.1 方案 A直接下载官方预编译二进制我推荐这个在受限服务器上获取 Node.js最快也是最可靠的方法不是找各路安装脚本而是直接去 Node.js 官网下载针对目标平台的预编译包。以 Linux x64 环境为例下载和解压的过程一般是cd ~/packages curl -fsSLO https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz tar -xf node-v20.11.0-linux-x64.tar.xz -C ~/runtime mv ~/runtime/node-v20.11.0-linux-x64 ~/runtime/node执行完之后~/runtime/node/bin目录里就有了 node 和 npm。我习惯把解压出来的目录重命名成不带版本号的node这样将来升级时直接换目录、改软链不用大动 PATH。下载后建议做一下校验。官方发布页会提供 SHASUMS256.txt可以做一次 SHA-256 校验防止下载出错。命令是这样的cd ~/packages curl -fsSLO https://nodejs.org/dist/v20.11.0/SHASUMS256.txt grep node-v20.11.0-linux-x64.tar.xz SHASUMS256.txt | sha256sum -c -看到输出为 OK 才说明包是完整、可靠的。这一步在正式环境里很重要别觉得多余。有些服务器网络不好下载不完整解压时报错那时候再排查就费时间了。我再强调一次为什么选择二进制包而不是源码编译源码编译需要 make、gcc、python 等完整工具链编译一次要花一二十分钟而且中间出错的概率很高。官方预编译包是直接用目标平台编译好的解压即用是最短路径。2.2 方案 B用 nvm 安装 Node.js 作为备选如果你不想手动管版本nvmNode Version Manager也是一个很好的选择。它本身是纯 shell 脚本安装时不需要 root只往~/.nvm目录里装东西。安装和使用的流程大致是curl -fsS https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装脚本会把 nvm 的初始化代码追加到你的~/.bashrc里。重新加载配置文件后就能用nvm install来装 Node.js 了source ~/.bashrc nvm install 20 nvm use 20用 nvm 的好处是版本切换灵活以后想升级或者给不同项目用不同版本只要几秒钟。但我个人在无 sudo 的部署场景里还是更倾向于方案 A原因很简单nvm 安装脚本每次都会走 GitHub 下载而某些公司内网访问 GitHub 非常不稳定反倒是 Node 官网的下载地址通常内网也能走通而且二进制包体积就十幾 MB传到服务器上也不费劲。具体选哪个取决于你的网络情况。两个方案都不需要 sudo所以并不冲突可以先试 A 不行再试 B。2.3 验证 npm 是否已经可用无论用方案 A 还是方案 B做的事情本质是一样的把 Node.js 的可执行文件放到用户目录并在 PATH 里暴露出来。验证是否成功只需要两行命令node -v npm -v不出意外的话第一行会输出版本号第二行也会输出一个版本号。看到这两行输出你手里就已经有了一个完全属于用户的 npm。之前系统里没有 npm 的尴尬到这一步就解决了。我实际操作时会再多验证一步看看 npm 默认的全局安装位置和缓存位置是否已经指向了用户目录npm config get prefix npm config get cache如果前缀是/home/yourname/.npm-global而不是/usr/local就说明后面npm install -g工具时不会碰到权限问题。如果前缀还是全局路径最好先用这两条命令纠正它npm config set prefix $HOME/.npm-global npm config set cache $HOME/.npm-cache全局 npm 包安装到用户目录之后可执行文件会放在$HOME/.npm-global/bin。我前面在 PATH 里已经加了$HOME/.local/bin这里顺便建议把$HOME/.npm-global/bin也加进去否则npm install -g装出来的命令经常让你明明装了却提示 command not found那感觉非常难受。3. 项目依赖处理没有全局 npm 也能装好 claude 的依赖3.1 直接用项目自带的 npm 运行 install拿到 node 和 npm 之后最自然的做法就是走进 claude 项目目录执行cd ~/claude npm install如果项目依赖不多、网络又通畅这一步通常能顺利跑完所有依赖都会装进~/claude/node_modules。但这只是理想情况。在真实受限环境里你会遇到至少两种比较麻烦的问题。第一种是网络问题。有些服务器访问默认 npm 源速度很慢或者根本访问不通。处理办法是把 npm 源切到某个镜像源这一步不需要任何权限只需要改 npm 配置npm config set registry https://registry.npmmirror.com换好源之后再用npm install下载速度经常会有质的提升。要注意在公司内网环境里有时候内网本身就有 npm 代理源这时候你按着官方源配置反而跑不通直接问维护的人要内网仓库地址会更省事。第二种是原生模块编译问题。claude 这类项目里如果有better-sqlite3、bcrypt、sharp这类带原生二进制的模块它们在npm install时会尝试用 node-gyp 编译 C 代码或者从 GitHub Releases 下载预编译产物。如果你的服务器没有编译器或者网络无法访问 GitHub常见的报错是node-gyp rebuild失败、找不到python、找不到make、找不到v8::Object的头文件等。这个问题我不会放在后面讲因为处理思路不太一样。3.2 没有外网权限时的离线依赖方案还有一种场景是服务器处在剥离外网的隔离网络里npm 怎么配源都没用。这时候就需要“离线搬运”的思路。具体做法很简单在一台可以联网、并且能访问 npm 源的机器上把 claude 项目整个复制过来然后执行npm install装好依赖后把项目目录打包上传到目标服务器。由于 Node.js 的依赖安装逻辑基本就是把包解压到node_modules目录所以这个node_modules目录本身就是可以整体复制的大多数情况下直接把它放进项目目录就能跑。这里会有一个重要问题原生模块在不同的操作系统、不同的 glibc 版本、不同的 Node ABIApplication Binary Interface版本下可能不兼容。也就是说你在自己电脑 Linux 上编译出来的better-sqlite3拿到目标服务器上未必能加载可能出现Module version mismatch之类的报错。处理办法是我下面要讲的第二种细节。3.3 平台原生模块的正确处理姿势对于带原生代码的包最佳实践是让它在目标服务器上完成下载和编译而不是依赖你自己电脑上编译好的产物。但目标服务器往往又缺工具链这就形成了一个死结。我的做法是分情况处理。如果目标服务器有 gcc、make、python那问题就简单设置好正确的环境变量让 node-gyp 有东西可用。通常需要确保python3或者python在 PATH 里还要指定编译器的路径比如export CXXg export CCgcc export PYTHONpython3 npm install如果目标服务器连编译器都没有那就得找一个在目标平台上预编译好的版本。很多流行的原生模块都会在 npm 上发布 prebuilt binaries它们会根据package.json里的cpu和os字段自动选择对应平台的二进制包。这时只要网络能连到 npm 源或者模块作者指定的二进制下载地址npm install就会自己拉取合适版本不需要本地编译。问题是二进制下载地址往往指向 GitHub Releases内网访问不通就会失败。这时候可以试试在 npm 配置里设置代理或者让维护人员把相关二进制包放到内网仓库。如果你没法让目标服务器联网又需要原生模块最稳妥的办法是找一台和目标服务器相同架构、相似系统版本的机器在那上面装好依赖再把node_modules打包搬过去。这样虽然辛苦但基本可靠。我在实际部署 claude 时项目里有sqlite相关的模块目标服务器虽然能联网但从 GitHub 下载二进制始终超时最后我就是在一台同系统的跳板机上准备好node_modules后打成 tar 包传过去的问题才解决。3.4 手动安装依赖包的底线方案如果连npm install都没法用比如 npm 本身坏了或者依赖特别复杂导致各种报错还有一个底线方案直接从 npm registry 上下载包的 tar 包手动塞进node_modules。npm 包的本质就是一个压缩成.tgz的目录包结构在package.json里写明。你可以用 curl 从 registry 直接拉包cd ~/packages curl -fsSLO https://registry.npmjs.org/some-package/-/some-package-1.2.3.tgz tar -xf some-package-1.2.3.tgz -C ~/claude/node_modules/some-package注意 tar 解压之后会多一层package目录所以解压之前先建好目标目录然后把内容挪进去。手动装依赖非常麻烦只适合依赖数量很少、或者你实在没别的办法的情况。我一般只拿它来补一两个缺失的依赖不会用这个方式处理大型项目。4. 部署与启动没有 systemd 的常驻进程方案4.1 端口选多少高位端口与权限的关系claude 这类服务一般都会监听 HTTP 端口。服务器上如果你没有 root 权限直接监听 80 端口会失败报错信息通常是EACCES: permission denied, bind之类。操作系统规定小于 1024 的端口只有 root 能绑定所以项目配置里的端口必须改成高位端口比如 8080、18080、30000只要大于 1024 且没被占用就行。改端口的位置一般是项目的配置文件claude 项目很可能支持用环境变量覆盖比如PORT18080。如果没有这种设计就去找配置文件里的port字段改一下。别忘了改了端口之后访问 URL 也会变成http://服务器IP:18080如果前面有网关或者反向代理就要把代理转发规则也改成这个端口。还有一个很常见的问题是服务器往往有自己的防火墙外网端口不一定开放。这时候单独改服务端口没用你得确认这个端口已经在防火墙白名单里。如果是公司内网服务器通常会有安全组或者防火墙规则需要申请开通。4.2 用 nohup 和 setsid 让进程在退出 SSH 后继续运行没有 systemd 权限不等于没法跑常驻服务。一个最简单的保活方式就是nohup。它的作用是让命令忽略挂断信号即使你关闭 SSH 会话进程也不会被 SIGHUP 杀掉。标准命令是这样的cd ~/claude nohup node server.js ~/claude/logs/app.log 21 这里 ~/claude/logs/app.log把标准输出重定向到日志文件21把错误输出也合并过去最后的是让命令在后台执行。执行完之后终端会显示一个 PID这个 ID 就是进程号你可以用ps -ef | grep node再次确认。但我个人更喜欢用setsid配合nohup因为setsid能让进程完全脱离当前会话即使终端窗口关闭进程也不会受到终端影响的干扰。命令长这样setsid nohup node server.js ~/claude/logs/app.log 21 setsid不是所有系统都有但大多数 Linux 都自带属于 util-linux 包。如果确实没有也可以只用nohup。只要测试下来 SSH 断开之后进程还活着就算成功了。4.3 用 tmux 做轻量守护方便随时进入现场如果服务需要交互式操作或者你想随时查看 claude 的运行输出tmux 是一个比 nohup 舒服得多的方案。tmux 本来是一个终端复用工具但它经常被用来当作简单的守护方案因为 tmux 会话在你断开 SSH 后会继续存在里面的进程自然也不会被杀。问题是在没有 sudo 的服务器上tmux 大概率没装。解决办法是自己编译安装一个到用户目录。编译 tmux 需要先装依赖比较麻烦但如果服务器上有 apt 相关的离线包或者你已经把编译好的二进制传上去就能直接用。我因为不想在这个环节浪费太多时间所以没有选 tmux而是用 nohup 日志文件的方式需要看运行情况时直接看日志就行。如果你确实喜欢 tmux可以试试pip install --user tmux这种不太常规的方式不过我不太推荐在这台机器上花太多时间。4.4 自己写一个 30 行的保活脚本服务跑起来之后万一它因为异常崩溃退出不会有人自动把它拉起来。系统里如果没有 supervisor、pm2 这类工具也没权限装可以自己写一个非常简单的 shell 脚本每隔几十秒检查一次进程是否活着死了就重新拉起。我写过一个最小可用的版本大致思路是这样的#!/bin/bash APP_HOME$HOME/claude PID_FILE$APP_HOME/claude.pid LOG_FILE$APP_HOME/logs/app.log START_CMDnode server.js while true; do if [ -f $PID_FILE ]; then PID$(cat $PID_FILE) if ! kill -0 $PID 2/dev/null; then echo [$(date)] process died, restarting ... $APP_HOME/logs/watchdog.log cd $APP_HOME setsid nohup $START_CMD $LOG_FILE 21 echo $! $PID_FILE fi else cd $APP_HOME setsid nohup $START_CMD $LOG_FILE 21 echo $! $PID_FILE fi sleep 30 done这个脚本用kill -0探测进程是否存活这是比较优雅的做法不会误杀其他进程。PID 文件是防止同时跑多个实例的关键。启动服务的入口命令我是通过node server.js来启动的实际项目如果入口是npm start可以改成node路径下的具体启动命令用 npm 再把启动变成间接方式反而增加一层出错可能。我用chmod x给脚本加好执行权限用setsid nohup ./watchdog.sh /dev/null 21 把保活脚本本身也放到后台。这样即使 claude 进程崩溃最多 30 秒就会被拉起来。日志里能看到重启记录方便排查。4.5 进程管理辅助用什么工具看进程和杀进程在没有 root 权限的环境里你能管理的是自己启动的进程。查看进程用ps是最直接的ps -ef | grep node如果你想把某个进程杀掉用kill命令需要以进程所有者的身份执行。这个没问题因为服务是你自己起的kill 12345如果进程没反应再尝试kill -9 12345。需要注意的是kill -9不会给进程任何清理机会可能留下未写完的数据不是万不得已尽量别用。我在实际中更常用的组合是先kill等五秒再检查是否还有进程存留确认死透了再重新启动。5. 常见问题与排查技巧我在这个过程中踩过的坑5.1 端口被占用或权限不足如果你在启动时看到EADDRINUSE: address already in use说明端口被别的进程占用了。用ss -lntp或者netstat -lntp看看哪个进程在用这个端口换成空闲端口就行。如果是EACCES基本就是绑定了 1024 以下的端口。记住默认把端口配置成高位端口比如 18080。我当时犯过一个低级错误明明把项目端口改成 18080 了启动日志依然报EACCES后来发现是项目读取配置的顺序有问题环境变量没生效还是用了默认的 80。所以建议启动前先确认配置真的被正确读取可以在项目启动逻辑里打印一行监听端口的信息。5.2 依赖下载慢或失败依赖下载失败最常见的原因是网络源不稳定。先确认 npm 源配置npm config get registry如果速度还是不行找一个合适的镜像源。要注意的是部分镜像同步更新会有点延迟某些冷门包可能出现版本不全的情况。如果你需要的包在镜像源里找不到可以临时把它切回官方源安装npm install some-package --registryhttps://registry.npmjs.org/如果整体网络都不好就退回离线方案把node_modules打包搬运过去我前面已经写过这里不再重复。5.3 node 进程内存不足claude 这类服务如果开着较长时间偶发内存不足是正常的。Node.js V8 引擎有一个旧空间内存上限默认在 64 位系统上大约是 4GB但在小内存服务器上可能还没到那个值就被系统 OOM 杀掉了。可以通过环境变量调整export NODE_OPTIONS--max-old-space-size2048但注意不要设得比物理内存还高否则进程更容易被系统杀掉。如果服务器内存只有 1GB可以设成--max-old-space-size768给别的进程留一点余量。5.4 node-gyp 编译失败如果你在npm install时遇到gyp ERR!相关的报错先冷静检查两件事一是编译器是否存在二是 Python 版本是否合适。node-gyp 现在一般需要 Python 3.6 以上。如果你的系统 Python 版本过老可能需要指定一个可用的 Python 解释器npm config set python /usr/bin/python3如果你的服务器真的没有编译器要么找预编译二进制包要么放弃原生模块换一个纯 JS 的替代库。我在部署 claude 时恰好碰到过 sqlite 模块编译失败当时检查发现是make没装但系统里有gcc。后来我换成了better-sqlite3的 prebuilt 版本路径绕过了本地编译。5.5 进程跑着跑着就没了最常见的原因有两个一是内存不足被 OOM killer 杀掉二是父进程退出时把子进程带走了。前者的排查方法是查看系统日志或者dmesg | tail里是否有 Out of memory后者则是没有正确脱离终端会话导致。解决第二个问题的标准操作就是我前面说过的setsid和nohup组合。如果你发现nohup之后 SSH 一关进程还是消失那多半是启动命令本身因为环境变量不同而报错进程在几秒内就崩了。这时候一定要去看日志文件别光盯着进程列表。5.6 修改配置文件不生效claude 类的项目有时会读.env文件或 JSON 配置。改完之后没生效通常是启动方式没有重新加载或者配置路径找错了。建议先追一下项目代码里配置加载的逻辑知道它优先读哪个文件再把环境变量和文件内容保持一致。多一份细心后面的排查成本会低很多。6. 经验总结无 sudo 部署的本质是“环境自包含”整套流程走下来我的体会其实可以精炼成一句话在受限服务器上部署服务不是把自己变成管理员而是把“管理员该做的那些事”全部放到自己的用户空间里重新做一遍。你要自己准备运行时、准备依赖、准备保活机制甚至要自己准备日志轮转和开机自启的替代方案。这个过程看起来很折腾但它给你很强的环境控制力——你可以完全掌控这个应用依赖了哪些东西、放在哪里、怎么启动整个目录之下就是一个可以随时删除重建的沙箱。如果你接下来要在这类环境里部署别的服务我的建议是永远先做环境侦察列出可用工具和不可用工具永远保持安装目录和项目目录分开方便整体迁移永远把启动方式和日志输出写到一份脚本里不要每次手动敲一长串命令。还有一个小技巧是我后来才学会的即使没有 sudo也可以在一些软件官网直接下载官方编译好的二进制包很多基础工具不只是 Node.js都支持免安装解压运行这是一个比源码编译轻量得多的获取软件的方式值得长期复用。
做过一次挺有代表性的部署一台老服务器账号是普通用户没有 sudo连 npm 都没有全局装过却要把一个叫 claude 的服务跑起来。这个 claude 项目不是那种一条命令就能装的单体包它依赖 Node.js 运行环境、若干 npm 包还需要常驻进程。刚拿到环境的时候我在终端里敲node -v返回 command not found敲npm -v同样提示找不到命令心里其实有点发凉。但后来冷静下来把事情拆开看发现这类“受限服务器部署”根本没那么神秘核心就一句话所有东西都装进自己的用户目录所有路径都用自己的环境变量所有进程都用普通权限能控制的守护方式跑起来。这篇文章不是某个产品的官方文档而是我从实际部署里总结出来的完整路线。你手头如果也有 claude、一个 Node.js 服务、某个 Web 应用甚至是一个 Python 写的程序只要面临同样的限制条件这套思路都能直接迁移。我会把每一步为什么这么做、命令怎么写、有哪些坑讲清楚尤其会写那些常规文档里不会告诉你的事比如没有 npm 时怎么处理依赖、没有 systemd 时怎么保活进程、端口权限不够怎么办。读完你完全可以照着在自己账号下复现一遍。1. 受限环境下的部署思路不要和系统硬刚1.1 先搞清楚“没有 sudo 和 npm”到底意味着什么很多人一看到“没有 sudo”就觉得什么都干不了其实不是。没有 sudo 只是意味着你不能动/usr、/opt、/etc这些系统目录不能安装系统级的软件包不能修改系统服务配置。但你自己的家目录是完整拥有的你能执行 shell能写文件能编译程序能监听高位端口能在用户态跑任意普通进程。这就是用户态部署的立足点。没有 npm 更是一个表面问题。npm 本质是 Node.js 发行包里自带的一个工具当系统里没有全局 npm 时你依然可以下载 Node.js 的预编译二进制包解压到自己的目录下里面的bin目录里就有 node 和 npm。也就是说npm 不是独立于 Node 之外的系统组件它是 Node 官方发行包的一部分。只要你有办法获得一份 Node.js 二进制文件npm 自然就有了。真正的难点其实在别处一是怎么在没有 root 权限的情况下获得可靠的运行时二是怎么处理项目依赖尤其是依赖里那些需要编译原生模块的包三是怎么让服务在自己退出 SSH 之后还在跑。这三件事解决掉部署就完成了一大半。我当时的做法是先做一次环境侦察把系统里有的工具、没有的工具全部列出来再决定部署路径。侦察命令无非是这几条uname -a cat /etc/os-release which curl wget tar gzip make gcc g python3 git echo $HOME df -h ./这里每一条都有意义。uname -a看内核架构比如 x86_64 还是 aarch64这个直接决定你该下载哪个平台的 Node.js 二进制包。cat /etc/os-release看发行版和版本虽然用户态部署通常不用太关心发行版但某些预编译二进制对 glibc 版本有要求提前看清楚能少走弯路。which那一条是检查你有没有下载工具、解压工具、编译工具链这决定了后面是用官方二进制包还是走源码编译。df -h是看磁盘空间有些服务器/home分区本身就很小装几个大依赖可能就爆了。侦察完我心里就有了谱。这台机器是 x86_64 架构curl 和 tar 都在gcc 和 make 也装了但 git 没装python3 在但版本比较老。这个条件已经足够走“官方二进制包 手动解压”这条路了。1.2 用户态部署的核心逻辑自包含、可回滚、不污染系统把整套运行环境放进自己的目录里本质上是构建一个自包含沙箱。这个做法的好处很直观你不需要任何系统权限就能反复折腾装坏了也不影响其他人顶多把自己目录里的文件删掉重来。具体怎么组织目录我建议从一开始就规划好不要随手乱扔。我的习惯是在家目录下面建这几个目录mkdir -p ~/runtime mkdir -p ~/claude mkdir -p ~/claude/logs mkdir -p ~/claude/data mkdir -p ~/packages~/runtime放运行时的二进制比如 Node.js 解压目录。~/claude放项目本体。~/claude/logs和~/claude/data分别放日志和运行数据。~/packages是用来存放手动下载的各种依赖包、tarball、离线缓存的地方这样将来初始化新环境时不用重新去网上找。然后就是设置环境变量。这一步非常关键我会把它写进~/.bashrc让每次登录时都能直接用export RUNTIME_HOME$HOME/runtime export NODE_HOME$RUNTIME_HOME/node export PATH$NODE_HOME/bin:$HOME/.local/bin:$PATH export NODE_PATH$NODE_HOME/lib/node_modules export NPM_CONFIG_PREFIX$HOME/.npm-global这里$HOME/.local/bin是一个用户态软件常用的安装位置很多工具支持用--prefix$HOME/.local安装到那里。提前把这个目录放进 PATH后面装一些辅助工具的时候会方便很多。PATH的顺序也有讲究用户目录的路径要放在系统路径前面这样系统里就算存在旧版本也优先用你的用户态版本。环境变量配好之后再用source ~/.bashrc让它生效。下次再登录这些命令就不用手动敲一遍了。2. 获取 Node.js 运行时不靠 sudo不靠 npm2.1 方案 A直接下载官方预编译二进制我推荐这个在受限服务器上获取 Node.js最快也是最可靠的方法不是找各路安装脚本而是直接去 Node.js 官网下载针对目标平台的预编译包。以 Linux x64 环境为例下载和解压的过程一般是cd ~/packages curl -fsSLO https://nodejs.org/dist/v20.11.0/node-v20.11.0-linux-x64.tar.xz tar -xf node-v20.11.0-linux-x64.tar.xz -C ~/runtime mv ~/runtime/node-v20.11.0-linux-x64 ~/runtime/node执行完之后~/runtime/node/bin目录里就有了 node 和 npm。我习惯把解压出来的目录重命名成不带版本号的node这样将来升级时直接换目录、改软链不用大动 PATH。下载后建议做一下校验。官方发布页会提供 SHASUMS256.txt可以做一次 SHA-256 校验防止下载出错。命令是这样的cd ~/packages curl -fsSLO https://nodejs.org/dist/v20.11.0/SHASUMS256.txt grep node-v20.11.0-linux-x64.tar.xz SHASUMS256.txt | sha256sum -c -看到输出为 OK 才说明包是完整、可靠的。这一步在正式环境里很重要别觉得多余。有些服务器网络不好下载不完整解压时报错那时候再排查就费时间了。我再强调一次为什么选择二进制包而不是源码编译源码编译需要 make、gcc、python 等完整工具链编译一次要花一二十分钟而且中间出错的概率很高。官方预编译包是直接用目标平台编译好的解压即用是最短路径。2.2 方案 B用 nvm 安装 Node.js 作为备选如果你不想手动管版本nvmNode Version Manager也是一个很好的选择。它本身是纯 shell 脚本安装时不需要 root只往~/.nvm目录里装东西。安装和使用的流程大致是curl -fsS https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装脚本会把 nvm 的初始化代码追加到你的~/.bashrc里。重新加载配置文件后就能用nvm install来装 Node.js 了source ~/.bashrc nvm install 20 nvm use 20用 nvm 的好处是版本切换灵活以后想升级或者给不同项目用不同版本只要几秒钟。但我个人在无 sudo 的部署场景里还是更倾向于方案 A原因很简单nvm 安装脚本每次都会走 GitHub 下载而某些公司内网访问 GitHub 非常不稳定反倒是 Node 官网的下载地址通常内网也能走通而且二进制包体积就十幾 MB传到服务器上也不费劲。具体选哪个取决于你的网络情况。两个方案都不需要 sudo所以并不冲突可以先试 A 不行再试 B。2.3 验证 npm 是否已经可用无论用方案 A 还是方案 B做的事情本质是一样的把 Node.js 的可执行文件放到用户目录并在 PATH 里暴露出来。验证是否成功只需要两行命令node -v npm -v不出意外的话第一行会输出版本号第二行也会输出一个版本号。看到这两行输出你手里就已经有了一个完全属于用户的 npm。之前系统里没有 npm 的尴尬到这一步就解决了。我实际操作时会再多验证一步看看 npm 默认的全局安装位置和缓存位置是否已经指向了用户目录npm config get prefix npm config get cache如果前缀是/home/yourname/.npm-global而不是/usr/local就说明后面npm install -g工具时不会碰到权限问题。如果前缀还是全局路径最好先用这两条命令纠正它npm config set prefix $HOME/.npm-global npm config set cache $HOME/.npm-cache全局 npm 包安装到用户目录之后可执行文件会放在$HOME/.npm-global/bin。我前面在 PATH 里已经加了$HOME/.local/bin这里顺便建议把$HOME/.npm-global/bin也加进去否则npm install -g装出来的命令经常让你明明装了却提示 command not found那感觉非常难受。3. 项目依赖处理没有全局 npm 也能装好 claude 的依赖3.1 直接用项目自带的 npm 运行 install拿到 node 和 npm 之后最自然的做法就是走进 claude 项目目录执行cd ~/claude npm install如果项目依赖不多、网络又通畅这一步通常能顺利跑完所有依赖都会装进~/claude/node_modules。但这只是理想情况。在真实受限环境里你会遇到至少两种比较麻烦的问题。第一种是网络问题。有些服务器访问默认 npm 源速度很慢或者根本访问不通。处理办法是把 npm 源切到某个镜像源这一步不需要任何权限只需要改 npm 配置npm config set registry https://registry.npmmirror.com换好源之后再用npm install下载速度经常会有质的提升。要注意在公司内网环境里有时候内网本身就有 npm 代理源这时候你按着官方源配置反而跑不通直接问维护的人要内网仓库地址会更省事。第二种是原生模块编译问题。claude 这类项目里如果有better-sqlite3、bcrypt、sharp这类带原生二进制的模块它们在npm install时会尝试用 node-gyp 编译 C 代码或者从 GitHub Releases 下载预编译产物。如果你的服务器没有编译器或者网络无法访问 GitHub常见的报错是node-gyp rebuild失败、找不到python、找不到make、找不到v8::Object的头文件等。这个问题我不会放在后面讲因为处理思路不太一样。3.2 没有外网权限时的离线依赖方案还有一种场景是服务器处在剥离外网的隔离网络里npm 怎么配源都没用。这时候就需要“离线搬运”的思路。具体做法很简单在一台可以联网、并且能访问 npm 源的机器上把 claude 项目整个复制过来然后执行npm install装好依赖后把项目目录打包上传到目标服务器。由于 Node.js 的依赖安装逻辑基本就是把包解压到node_modules目录所以这个node_modules目录本身就是可以整体复制的大多数情况下直接把它放进项目目录就能跑。这里会有一个重要问题原生模块在不同的操作系统、不同的 glibc 版本、不同的 Node ABIApplication Binary Interface版本下可能不兼容。也就是说你在自己电脑 Linux 上编译出来的better-sqlite3拿到目标服务器上未必能加载可能出现Module version mismatch之类的报错。处理办法是我下面要讲的第二种细节。3.3 平台原生模块的正确处理姿势对于带原生代码的包最佳实践是让它在目标服务器上完成下载和编译而不是依赖你自己电脑上编译好的产物。但目标服务器往往又缺工具链这就形成了一个死结。我的做法是分情况处理。如果目标服务器有 gcc、make、python那问题就简单设置好正确的环境变量让 node-gyp 有东西可用。通常需要确保python3或者python在 PATH 里还要指定编译器的路径比如export CXXg export CCgcc export PYTHONpython3 npm install如果目标服务器连编译器都没有那就得找一个在目标平台上预编译好的版本。很多流行的原生模块都会在 npm 上发布 prebuilt binaries它们会根据package.json里的cpu和os字段自动选择对应平台的二进制包。这时只要网络能连到 npm 源或者模块作者指定的二进制下载地址npm install就会自己拉取合适版本不需要本地编译。问题是二进制下载地址往往指向 GitHub Releases内网访问不通就会失败。这时候可以试试在 npm 配置里设置代理或者让维护人员把相关二进制包放到内网仓库。如果你没法让目标服务器联网又需要原生模块最稳妥的办法是找一台和目标服务器相同架构、相似系统版本的机器在那上面装好依赖再把node_modules打包搬过去。这样虽然辛苦但基本可靠。我在实际部署 claude 时项目里有sqlite相关的模块目标服务器虽然能联网但从 GitHub 下载二进制始终超时最后我就是在一台同系统的跳板机上准备好node_modules后打成 tar 包传过去的问题才解决。3.4 手动安装依赖包的底线方案如果连npm install都没法用比如 npm 本身坏了或者依赖特别复杂导致各种报错还有一个底线方案直接从 npm registry 上下载包的 tar 包手动塞进node_modules。npm 包的本质就是一个压缩成.tgz的目录包结构在package.json里写明。你可以用 curl 从 registry 直接拉包cd ~/packages curl -fsSLO https://registry.npmjs.org/some-package/-/some-package-1.2.3.tgz tar -xf some-package-1.2.3.tgz -C ~/claude/node_modules/some-package注意 tar 解压之后会多一层package目录所以解压之前先建好目标目录然后把内容挪进去。手动装依赖非常麻烦只适合依赖数量很少、或者你实在没别的办法的情况。我一般只拿它来补一两个缺失的依赖不会用这个方式处理大型项目。4. 部署与启动没有 systemd 的常驻进程方案4.1 端口选多少高位端口与权限的关系claude 这类服务一般都会监听 HTTP 端口。服务器上如果你没有 root 权限直接监听 80 端口会失败报错信息通常是EACCES: permission denied, bind之类。操作系统规定小于 1024 的端口只有 root 能绑定所以项目配置里的端口必须改成高位端口比如 8080、18080、30000只要大于 1024 且没被占用就行。改端口的位置一般是项目的配置文件claude 项目很可能支持用环境变量覆盖比如PORT18080。如果没有这种设计就去找配置文件里的port字段改一下。别忘了改了端口之后访问 URL 也会变成http://服务器IP:18080如果前面有网关或者反向代理就要把代理转发规则也改成这个端口。还有一个很常见的问题是服务器往往有自己的防火墙外网端口不一定开放。这时候单独改服务端口没用你得确认这个端口已经在防火墙白名单里。如果是公司内网服务器通常会有安全组或者防火墙规则需要申请开通。4.2 用 nohup 和 setsid 让进程在退出 SSH 后继续运行没有 systemd 权限不等于没法跑常驻服务。一个最简单的保活方式就是nohup。它的作用是让命令忽略挂断信号即使你关闭 SSH 会话进程也不会被 SIGHUP 杀掉。标准命令是这样的cd ~/claude nohup node server.js ~/claude/logs/app.log 21 这里 ~/claude/logs/app.log把标准输出重定向到日志文件21把错误输出也合并过去最后的是让命令在后台执行。执行完之后终端会显示一个 PID这个 ID 就是进程号你可以用ps -ef | grep node再次确认。但我个人更喜欢用setsid配合nohup因为setsid能让进程完全脱离当前会话即使终端窗口关闭进程也不会受到终端影响的干扰。命令长这样setsid nohup node server.js ~/claude/logs/app.log 21 setsid不是所有系统都有但大多数 Linux 都自带属于 util-linux 包。如果确实没有也可以只用nohup。只要测试下来 SSH 断开之后进程还活着就算成功了。4.3 用 tmux 做轻量守护方便随时进入现场如果服务需要交互式操作或者你想随时查看 claude 的运行输出tmux 是一个比 nohup 舒服得多的方案。tmux 本来是一个终端复用工具但它经常被用来当作简单的守护方案因为 tmux 会话在你断开 SSH 后会继续存在里面的进程自然也不会被杀。问题是在没有 sudo 的服务器上tmux 大概率没装。解决办法是自己编译安装一个到用户目录。编译 tmux 需要先装依赖比较麻烦但如果服务器上有 apt 相关的离线包或者你已经把编译好的二进制传上去就能直接用。我因为不想在这个环节浪费太多时间所以没有选 tmux而是用 nohup 日志文件的方式需要看运行情况时直接看日志就行。如果你确实喜欢 tmux可以试试pip install --user tmux这种不太常规的方式不过我不太推荐在这台机器上花太多时间。4.4 自己写一个 30 行的保活脚本服务跑起来之后万一它因为异常崩溃退出不会有人自动把它拉起来。系统里如果没有 supervisor、pm2 这类工具也没权限装可以自己写一个非常简单的 shell 脚本每隔几十秒检查一次进程是否活着死了就重新拉起。我写过一个最小可用的版本大致思路是这样的#!/bin/bash APP_HOME$HOME/claude PID_FILE$APP_HOME/claude.pid LOG_FILE$APP_HOME/logs/app.log START_CMDnode server.js while true; do if [ -f $PID_FILE ]; then PID$(cat $PID_FILE) if ! kill -0 $PID 2/dev/null; then echo [$(date)] process died, restarting ... $APP_HOME/logs/watchdog.log cd $APP_HOME setsid nohup $START_CMD $LOG_FILE 21 echo $! $PID_FILE fi else cd $APP_HOME setsid nohup $START_CMD $LOG_FILE 21 echo $! $PID_FILE fi sleep 30 done这个脚本用kill -0探测进程是否存活这是比较优雅的做法不会误杀其他进程。PID 文件是防止同时跑多个实例的关键。启动服务的入口命令我是通过node server.js来启动的实际项目如果入口是npm start可以改成node路径下的具体启动命令用 npm 再把启动变成间接方式反而增加一层出错可能。我用chmod x给脚本加好执行权限用setsid nohup ./watchdog.sh /dev/null 21 把保活脚本本身也放到后台。这样即使 claude 进程崩溃最多 30 秒就会被拉起来。日志里能看到重启记录方便排查。4.5 进程管理辅助用什么工具看进程和杀进程在没有 root 权限的环境里你能管理的是自己启动的进程。查看进程用ps是最直接的ps -ef | grep node如果你想把某个进程杀掉用kill命令需要以进程所有者的身份执行。这个没问题因为服务是你自己起的kill 12345如果进程没反应再尝试kill -9 12345。需要注意的是kill -9不会给进程任何清理机会可能留下未写完的数据不是万不得已尽量别用。我在实际中更常用的组合是先kill等五秒再检查是否还有进程存留确认死透了再重新启动。5. 常见问题与排查技巧我在这个过程中踩过的坑5.1 端口被占用或权限不足如果你在启动时看到EADDRINUSE: address already in use说明端口被别的进程占用了。用ss -lntp或者netstat -lntp看看哪个进程在用这个端口换成空闲端口就行。如果是EACCES基本就是绑定了 1024 以下的端口。记住默认把端口配置成高位端口比如 18080。我当时犯过一个低级错误明明把项目端口改成 18080 了启动日志依然报EACCES后来发现是项目读取配置的顺序有问题环境变量没生效还是用了默认的 80。所以建议启动前先确认配置真的被正确读取可以在项目启动逻辑里打印一行监听端口的信息。5.2 依赖下载慢或失败依赖下载失败最常见的原因是网络源不稳定。先确认 npm 源配置npm config get registry如果速度还是不行找一个合适的镜像源。要注意的是部分镜像同步更新会有点延迟某些冷门包可能出现版本不全的情况。如果你需要的包在镜像源里找不到可以临时把它切回官方源安装npm install some-package --registryhttps://registry.npmjs.org/如果整体网络都不好就退回离线方案把node_modules打包搬运过去我前面已经写过这里不再重复。5.3 node 进程内存不足claude 这类服务如果开着较长时间偶发内存不足是正常的。Node.js V8 引擎有一个旧空间内存上限默认在 64 位系统上大约是 4GB但在小内存服务器上可能还没到那个值就被系统 OOM 杀掉了。可以通过环境变量调整export NODE_OPTIONS--max-old-space-size2048但注意不要设得比物理内存还高否则进程更容易被系统杀掉。如果服务器内存只有 1GB可以设成--max-old-space-size768给别的进程留一点余量。5.4 node-gyp 编译失败如果你在npm install时遇到gyp ERR!相关的报错先冷静检查两件事一是编译器是否存在二是 Python 版本是否合适。node-gyp 现在一般需要 Python 3.6 以上。如果你的系统 Python 版本过老可能需要指定一个可用的 Python 解释器npm config set python /usr/bin/python3如果你的服务器真的没有编译器要么找预编译二进制包要么放弃原生模块换一个纯 JS 的替代库。我在部署 claude 时恰好碰到过 sqlite 模块编译失败当时检查发现是make没装但系统里有gcc。后来我换成了better-sqlite3的 prebuilt 版本路径绕过了本地编译。5.5 进程跑着跑着就没了最常见的原因有两个一是内存不足被 OOM killer 杀掉二是父进程退出时把子进程带走了。前者的排查方法是查看系统日志或者dmesg | tail里是否有 Out of memory后者则是没有正确脱离终端会话导致。解决第二个问题的标准操作就是我前面说过的setsid和nohup组合。如果你发现nohup之后 SSH 一关进程还是消失那多半是启动命令本身因为环境变量不同而报错进程在几秒内就崩了。这时候一定要去看日志文件别光盯着进程列表。5.6 修改配置文件不生效claude 类的项目有时会读.env文件或 JSON 配置。改完之后没生效通常是启动方式没有重新加载或者配置路径找错了。建议先追一下项目代码里配置加载的逻辑知道它优先读哪个文件再把环境变量和文件内容保持一致。多一份细心后面的排查成本会低很多。6. 经验总结无 sudo 部署的本质是“环境自包含”整套流程走下来我的体会其实可以精炼成一句话在受限服务器上部署服务不是把自己变成管理员而是把“管理员该做的那些事”全部放到自己的用户空间里重新做一遍。你要自己准备运行时、准备依赖、准备保活机制甚至要自己准备日志轮转和开机自启的替代方案。这个过程看起来很折腾但它给你很强的环境控制力——你可以完全掌控这个应用依赖了哪些东西、放在哪里、怎么启动整个目录之下就是一个可以随时删除重建的沙箱。如果你接下来要在这类环境里部署别的服务我的建议是永远先做环境侦察列出可用工具和不可用工具永远保持安装目录和项目目录分开方便整体迁移永远把启动方式和日志输出写到一份脚本里不要每次手动敲一长串命令。还有一个小技巧是我后来才学会的即使没有 sudo也可以在一些软件官网直接下载官方编译好的二进制包很多基础工具不只是 Node.js都支持免安装解压运行这是一个比源码编译轻量得多的获取软件的方式值得长期复用。
