npm SSH 配置问题解决方案

问题背景

@whiskeysockets/baileys 依赖 libsignal-node，而 libsignal-node 是从 GitHub 下载的原生 C++ 模块。npm install 时，这个依赖的编译过程会通过 SSH 访问 GitHub，导致以下错误：

Permission denied (publickey)
fatal: Could not read from remote repository

这个错误影响所有平台：Windows、macOS、Linux（包括容器内部）。

解决方案概述

本项目采用 多层配置策略，确保 npm/git 使用 HTTPS 而不是 SSH 访问 GitHub：

1️⃣ npm 配置 (.npmrc)

文件: .npmrc

git-protocol=https
fetch-timeout=120000
fetch-retry-mintimeout=20000
fetch-retry-maxtimeout=120000

作用: 告诉 npm 使用 HTTPS 协议访问 git 仓库，并增加超时时间以应对网络延迟。

2️⃣ postinstall 脚本自动配置

文件: scripts/postinstall.js

在 npm install 完成后自动配置 git 的 URL 重定向：

git config url."https://github.com/".insteadOf ssh://git@github.com/
git config url."https://".insteadOf git://

这样 git 会自动将 SSH URLs 转换为 HTTPS。

3️⃣ Docker 镜像全局配置

文件: Dockerfile, Dockerfile.sandbox, Dockerfile.sandbox-browser

在容器构建时全局配置 git：

RUN git config --global url."https://github.com/".insteadOf ssh://git@github.com/
RUN git config --global url."https://".insteadOf git://

4️⃣ 手动配置脚本（可选）

文件: scripts/setup-npm-git-config.sh

如果需要手动设置 git 配置：

# 项目级别配置
bash scripts/setup-npm-git-config.sh

# 全局配置（需要 sudo）
sudo bash scripts/setup-npm-git-config.sh --global

如何使用

本地开发

1. 首次 clone 项目

   git clone https://github.com/clawdbot/clawdbot.git
   cd clawdbot

2. 安装依赖

   pnpm install

   postinstall 脚本会自动：

   • 配置 git URL 重定向
   • 设置 git 钩子
   • 应用补丁文件

Docker 部署

所有 Dockerfile 已预配置，直接构建即可：

docker build -t clawdbot:latest .
docker build -f Dockerfile.sandbox -t clawdbot:sandbox .
docker build -f Dockerfile.sandbox-browser -t clawdbot:sandbox-browser .

CI/CD 环境

在 GitHub Actions 或其他 CI/CD 中，.npmrc 配置会自动应用。如果需要额外配置：

- name: Setup npm git config
  run: bash scripts/setup-npm-git-config.sh
  
- name: Install dependencies
  run: pnpm install

配置优先级

Git 会按以下顺序应用配置（后面的覆盖前面的）：

1. 系统级 (/etc/gitconfig)
2. 用户级 (~/.gitconfig)
3. 项目级 (.git/config - 在 postinstall 中设置)
4. .npmrc 中的 git-protocol=https

故障排除

如果仍然出现 SSH 错误

方案 1: 手动配置 git

git config url."https://github.com/".insteadOf ssh://git@github.com/
git config url."https://".insteadOf git://

方案 2: 删除 node_modules 重新安装

rm -rf node_modules pnpm-lock.yaml
pnpm install

方案 3: 清除 npm 缓存

npm cache clean --force
pnpm install

检查当前配置

# 查看项目级 git 配置
git config --list --local | grep url

# 查看全局 git 配置
git config --list --global | grep url

# 查看 npm 配置
npm config list | grep git

技术细节

为什么需要这个配置？

• npm 内部使用 git 克隆 libsignal-node
• npm 在某些情况下会将 HTTPS git URLs 转换为 SSH
• SSH 需要正确的密钥配置和访问权限
• HTTPS 使用账户授权（GitHub Personal Access Token）或直接公开访问

为什么 git-protocol=https 还不够？

• npm 仍然可能在某些环境中转换为 SSH
• git 自身的 URL 重定向规则优先级更高
• 同时配置 npm 和 git 确保全覆盖

Windows 上是否有效？

是的。git 和 npm 在 Windows 上使用相同的 git 配置机制。

参考链接

• npm 文档：git-protocol
• Git 文档：url.<base>.insteadOf
• Baileys GitHub
• libsignal-node GitHub