无sudo权限的cPanel共享主机如何实现Node.js CI/CD流水线

全程不需要sudo权限，适配所有搭载cPanel Node.js Selector功能的共享主机，不需要额外安装全局服务。

前置准备 #

• 登录cPanel面板，确认已开通「Node.js应用」功能，提前创建好对应项目的Node.js应用，选择和本地开发一致的Node.js大版本，配置好项目根目录、启动文件路径，手动点击一次「启动」确认应用可正常运行
• 生成专用部署SSH密钥对，将公钥导入cPanel「SSH访问」板块的授权密钥列表，测试确认可通过私钥免密登录主机
• 将node_modules、.env、.git目录加入项目.gitignore规则，避免将依赖、敏感配置提交到代码仓库
• 记录cPanel自动生成的Node虚拟环境激活脚本路径，格式一般为/home/你的cPanel用户名/nodevenv/项目根目录名/你选择的Node版本/bin/activate，在cPanel Node.js应用详情页可以直接查到该路径

流水线核心逻辑 #

共享主机无root权限下，不要尝试全局安装PM2、nvm等工具，所有操作基于cPanel自带的托管能力实现：

• 代码通过SSH+rsync增量同步到主机目录，避免全量传输浪费时间
• 依赖安装在cPanel自动生成的用户级虚拟环境中，不需要系统级写入权限
• 应用重启通过Passenger的文件触发机制实现，不需要执行系统级服务操作命令

流水线配置（以GitHub Actions为例，GitLab CI/Gitea Actions逻辑完全通用） #

1. 配置仓库密钥 #

在代码仓库的密钥/变量配置页添加以下值，禁止硬编码到流水线文件中：

• CPANEL_SSH_KEY：部署用SSH私钥全文
• CPANEL_USER：cPanel账号用户名
• CPANEL_HOST：共享主机SSH连接地址
• CPANEL_PORT：共享主机SSH连接端口（多数cPanel主机不使用默认22端口，在SSH访问详情页可查）
• CPANEL_APP_PATH：主机上的项目根目录绝对路径
• CPANEL_VENV_ACTIVATE：之前记录的虚拟环境激活脚本绝对路径

2. 编写流水线配置文件 #

在项目中新建.github/workflows/deploy.yml文件，内容如下：

name: 生产环境部署
on:
  push:
    branches: [ main ] # 推送到main分支时自动触发部署
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4

      - name: 初始化SSH连接
        run: |
          mkdir -p ~/.ssh
          chmod 700 ~/.ssh
          echo "${{ secrets.CPANEL_SSH_KEY }}" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -p ${{ secrets.CPANEL_PORT }} ${{ secrets.CPANEL_HOST }} >> ~/.ssh/known_hosts
          chmod 644 ~/.ssh/known_hosts

      - name: 增量同步代码到主机
        run: |
          rsync -avz --delete -e "ssh -p ${{ secrets.CPANEL_PORT }}" ./ ${{ secrets.CPANEL_USER }}@${{ secrets.CPANEL_HOST }}:${{ secrets.CPANEL_APP_PATH }} \
          --exclude '.git' \
          --exclude '.github' \
          --exclude 'node_modules' \
          --exclude '.env' \
          --exclude '*.log'

      - name: 安装依赖&重启应用
        run: |
          ssh -p ${{ secrets.CPANEL_PORT }} ${{ secrets.CPANEL_USER }}@${{ secrets.CPANEL_HOST }} << 'EOF'
          source ${{ secrets.CPANEL_VENV_ACTIVATE }}
          cd ${{ secrets.CPANEL_APP_PATH }}
          npm ci --omit=dev
          # 前端类Node项目（Nuxt/Next/Vite SSR等）放开下行注释执行构建
          # npm run build
          # 触发Passenger自动重启应用，无权限要求
          touch tmp/restart.txt
          EOF

避坑说明 #

• 所有npm操作必须先激活cPanel生成的虚拟环境再执行，直接调用系统默认npm会出现权限不足、全局包安装失败的问题
• 不要手动执行kill命令杀Node进程，也不要尝试全局安装PM2托管进程，cPanel的Node应用由Phusion Passenger托管，只要更新项目tmp/restart.txt文件的修改时间，Passenger会自动完成应用重启，和cPanel上PHP应用的重启逻辑完全一致
• 项目环境变量直接在cPanel Node.js应用的设置页配置即可，不需要通过流水线传输.env文件，避免敏感信息泄露
• 首次运行流水线前，先手动SSH登录主机执行一次虚拟环境激活、依赖安装操作，确认目录所有者为当前cPanel用户，避免出现EACCES权限错误
• 如果rsync同步时报权限错误，直接在cPanel文件管理器中将项目目录权限设置为755即可，不需要执行带sudo的权限修改命令

内容的提问来源于stack exchange，提问作者Antonio