在日常的服务器部署和自动化流程里，GitHub 应该是最常用的代码托管平台了。但很多人第一次在服务器上用 HTTPS 方式拉取私有仓库代码时，都会碰到同一个尴尬场面：明明本地电脑上能正常 clone，服务器上输入账号密码却一直报Authentication failed。其实从 2021 年 8 月起，GitHub 就已经正式取消了密码用于 Git 操作的认证方式，现在唯一推荐的 HTTPS 认证手段就是 Personal Access Token。这篇文章就是围绕“用 classic token 拉取 GitHub 代码进行部署”这个场景，把从创建 token、配置权限、到在服务器上安全拉取代码、部署上线的整个链路，结合我自己的实际经验完整走一遍。
内容会比较细，适合正在做 CI/CD、服务器环境初始化、或者被 Git 认证坑过的同学参考。我会尽量把每一步的“为什么这么做”也讲清楚，而不是只丢给你几条命令。
1. 为什么要用 Token 而不是密码拉代码
1.1 GitHub 认证机制的变化
GitHub 在 2020 年 7 月就开始要求所有在 GitHub 上的操作使用基于令牌的认证，并在 2021 年 8 月 13 日正式移除了对账户密码进行 Git 操作的支持。也就是说，你再也不能在命令行里用用户名 + 密码的形式去git clone一个私有仓库。如果你硬要这么干，GitHub 会直接拒绝你的请求，返回一段很长的提示信息，告诉你需要使用 PAT 或者 SSH key。
对于服务器部署场景来说，这个变化影响很大。以前很多部署脚本里会写死密码，或者通过交互提示输入密码，现在这条路彻底堵死了。而 classic token 就是替代密码的一种访问凭据，它本质上是一串随机生成的字符串，通过 HTTP Header 或者 URL 参数的方式传给 GitHub 服务端，让它知道你是一个合法用户。
1.2 Classic Token 和 Fine-grained Token 的取舍
GitHub 现在同时支持两种 PAT：Classic Token 和 Fine-grained Token。Classic Token 是早期的模式，它可以访问你账号下所有有权限的仓库，权限范围通过repo、workflow之类的 scope 来控制。Fine-grained Token 是后来推出的精细化令牌，可以指定某一个仓库或某几个仓库，权限控制也更细致。
我用的最多的是 Classic Token，原因很直接：
- 配置简单，在命令行里用起来方便
- 很多老项目、旧版 CI 工具和部署脚本只支持 classic token
- Fine-grained Token 虽然更安全，但在部分 GitHub API 或第三方工具里还没完全覆盖，容易遇到兼容性问题
- 对于服务器拉代码这种单一用途，classic token 足够用了
所以在本文的场景里，我默认使用 classic token。
1.3 Token 为什么适合部署场景
Token 相比密码有几个很实际的好处：
- 可以有独立的过期时间，比如 90 天、180 天，即使泄露，风险窗口可控
- 可以只授权需要的权限，比如只给
repo，不会把你的账号完全暴露 - 可以随时吊销，不需要改密码
- 可以在 CI/CD 系统里作为 secret 变量存在，不直接暴露在代码里
尤其是在无人值守的服务器上，用 token 配合 Git 的凭据管理机制，可以做到一次性配置，之后git pull不再需要人工干预。
2. 创建 Classic Token 的完整流程与权限勾选
2.1 进入创建页面
登录 GitHub 后，点击右上角头像，选择Settings，然后在左侧菜单最底部找到Developer settings。接着进入Personal access tokens，再选择Tokens (classic)，最后点击Generate new token，选择Generate new token (classic)。
这里注意，很多人会误以为Fine-grained tokens是默认推荐选项，但对于经典场景，还是选Tokens (classic)最稳妥。
2.2 必填信息和权限设置
创建 classic token 时有几个东西需要填：
Note：给这个 token 起一个容易识别的名字，比如deploy-server-2025，方便日后管理Expiration：过期时间。我建议不要选No expiration，哪怕麻烦一点，也要定期更换。一般选 90 天比较合理，既能减少维护频率，又不至于让 token 长期有效Select scopes：这里是最关键的一步。如果你只是要拉取仓库代码，勾选repo就足够了
repo权限是整个 token 的核心权限，它包含对公共仓库和私有仓库的完整读写能力。如果你需要拉取代码后触发 GitHub Actions，还要额外勾选workflow。如果你要删除仓库或者修改仓库设置，才需要delete_repo等高级权限。
我见过很多人图省事，直接全选所有 scope，这其实非常危险。Token 一旦泄露，攻击者就能用你的账号做任何事。做部署用途的话，权限越小越好。
2.3 Token 显示与保存
点击Generate token之后，页面会显示一次完整的 token 字符串。注意，这个字符串只显示这一次，离开页面后就再也看不到完整内容了。GitHub 只会保留 token 的哈希值，用于后续校验，无法找回原文。
所以生成后要立刻复制保存到一个安全的地方，比如密码管理器。千万不要直接放到代码仓库或公共文档里。我自己会先把 token 存到服务器的环境变量文件里，同时保存一份到本地的密码管理器，双重备份。
2.4 实际操作中的一个细节
如果你在创建 token 时服务器环境已经存在几个旧 token，建议顺手在Tokens (classic)列表里检查一下有没有已经不用了的，直接Delete掉。避免积累过多缺乏管理的 token，这也是安全习惯。
3. 在服务器上使用 Token 拉取代码的几种姿势
3.1 最直接的方法：URL 内嵌 token
拿到 token 后，最直接的 clone 方式是这种：
git clone https://用户名:TOKEN@github.com/用户名/仓库名.git比如：
git clone https://myaccount:ghp_xxxx123456@github.com/myaccount/myproject.git这里的用户名是你的 GitHub 登录名，TOKEN是刚刚生成的 classic token。这种方式适合临时手动操作，跑完命令后就能把仓库拉到本地。
但它的缺点也很明显：
- Token 会出现在 shell 历史记录里
- 如果你敲命令时有人在看屏幕，token 可能被看到
- 如果后续
git remote -v查看远程地址，也会暴露出 token，不小心输出到日志里就是事故
所以我一般只在调试的时候用这种方式，正式的部署脚本绝不这么写。
3.2 更安全的方法：使用环境变量注入
在部署脚本里，推荐用环境变量来传 token。比如：
export GITHUB_TOKEN="ghp_xxxx123456" git clone https://x-access-token:${GITHUB_TOKEN}@github.com/myaccount/myproject.git这里用x-access-token作为用户名，并不是必须的，但 GitHub 官方文档里推荐过这种写法，可以避免某些场景下 url 解析错误。在 CI/CD 系统里，你可以把GITHUB_TOKEN配置成 secret 变量，运行时动态注入到环境里，这样就不会把 token 写死在脚本文件里。
3.3 一劳永逸的方法：Git 凭据管理器
对于自己长期维护的服务器，我更推荐用 Git 自带的凭据存储功能，让git clone过程只出现一次认证，之后所有git pull都自动携带 token，不需要每次手动注入。
先做一次带 token 的 clone 或者远程更新，然后配置 credential helper：
git config --global credential.helper store然后执行一次：
git clone https://x-access-token:${GITHUB_TOKEN}@github.com/myaccount/myproject.git之后 Git 会把 URL 中的用户名和 token 写入~/.git-credentials文件。后续同一主机下的git pull就会自动复用这个凭据。
不过请注意：store模式的凭据是明文存储在用户目录下的。如果服务器上还有其他用户，或者你觉得这台机器的安全性不够高，建议改用cache模式，让 token 只在内存中保留一段时间：
git config --global credential.helper 'cache --timeout=3600'这样 token 会在 3600 秒内缓存，过期后重新认证一次即可。如果用的是 Linux 服务器做单用户部署，store模式其实也能接受，只要管理好文件权限就行。
3.4 不要在命令行直接敲 token
无论用哪种方式，我都强烈建议不要直接在交互式 shell 里把 token 作为明文参数打一遍。因为 shell 的历史记录文件（比如~/.bash_history）会保留你敲过的命令。哪怕你后面删了文件，也可能已经被日志系统采集走。
正确做法是把 token 写入一个只有当前用户可读的环境变量文件。比如：
cat > ~/.deploy_env <<'EOF' export GITHUB_TOKEN="ghp_xxxx123456" EOF chmod 600 ~/.deploy_env source ~/.deploy_env执行完再启动部署脚本，就不需要再在命令行里显式写出 token。
4. 部署场景的完整实践：从拉取到上线
4.1 部署前的服务器环境准备
假设我们有一台全新的 Ubuntu 服务器，想要把 GitHub 上的一个 Node.js 项目部署上去。首先确认服务器已经安装好 Git 和 Node.js：
sudo apt update sudo apt install -y git nodejs npm然后创建一个专门的部署用户，避免直接用 root 部署：
sudo adduser deploy sudo usermod -aG sudo deploy su - deploy部署用户的意义在于：即使 token 或者某个项目出错，也不会对服务器的系统文件造成致命影响。很多部署事故，都是从 root 权限执行了错误的rm -rf开始的。
4.2 拉取代码的完整步骤
登录部署用户后，创建目录结构：
mkdir -p /home/deploy/apps cd /home/deploy/apps然后设置环境变量并 clone：
export GITHUB_TOKEN="ghp_xxxx123456" git clone https://x-access-token:${GITHUB_TOKEN}@github.com/myaccount/myproject.git cd myproject如果项目本身是私有仓库，这一步就能正常拉下来了。如果是公共仓库，其实不需要任何认证，这也是很多人容易搞混的地方：公共仓库用git clone https://github.com/...即可，私有仓库才需要 token。
4.3 部署脚本示例
拉下来之后，通常还要做依赖安装、构建、启动三个环节。我写一个简单的部署脚本，逻辑很清晰：
#!/bin/bash set -e export GITHUB_TOKEN="ghp_xxxx123456" APP_NAME="myproject" APP_DIR="/home/deploy/apps/${APP_NAME}" REPO_URL="https://x-access-token:${GITHUB_TOKEN}@github.com/myaccount/${APP_NAME}.git" cd ${APP_DIR} echo "[1/4] 拉取最新代码" if [ ! -d "${APP_DIR}/.git" ]; then git clone ${REPO_URL} ${APP_DIR} else git pull origin main fi echo "[2/4] 安装依赖" npm install --production echo "[3/4] 构建项目" npm run build echo "[4/4] 重启服务" if systemctl list-units --type=service | grep -q "${APP_NAME}"; then sudo systemctl restart ${APP_NAME} else echo "服务不存在，请手动创建 systemd unit" fi这个脚本里有一个比较关键的细节：在git pull之前，需要确保 Git 能拿到 token。如果在脚本里通过环境变量 export 了 token，那么git pull时 Git 会解析远程 URL，自动把环境变量替换进去。但如果你使用的是 credential store，那这一步可以省略 token 的环境变量。
4.4 配置 systemd 服务实现持续部署
为了让服务能在后台稳定运行，我通常会配合 systemd 写一个 unit 文件。在/etc/systemd/system/myproject.service中：
[Unit] Description=My Project Service After=network.target [Service] User=deploy WorkingDirectory=/home/deploy/apps/myproject ExecStart=/usr/bin/node /home/deploy/apps/myproject/server.js Restart=always Environment=NODE_ENV=production [Install] WantedBy=multi-user.target这样写的好处是，服务崩溃后会自动拉起，服务器重启后服务也会自动启动。配合前面的部署脚本，整个流程就是：更新代码 -> 安装依赖 -> 构建 -> 重启服务，一气呵成。
4.5 用 Webhook 或定时任务做自动化
如果你不想每次手动去服务器上执行脚本，可以设置一个定时任务，每隔几分钟检查一次版本更新：
crontab -e */5 * * * * cd /home/deploy/apps/myproject && git pull origin main > /dev/null 2>&1 && npm run build && sudo systemctl restart myproject但这种方式有个问题，Git pull 也需要凭据。在坑里爬过几次后，我总结出一个更建议的方案：在部署脚本里统一管理 token 环境变量，然后用 CI/CD 平台（比如 GitHub Actions）在代码 push 后自动触发服务器上的部署脚本。这样 token 不需要放在服务器上，而是放在 CI 平台的 secret 里，安全性和便利性都好很多。
如果只有一台服务器并且没有 CI 平台，那退回定时任务 + credential helper 也完全够用。
5. 常见问题与排查技巧实录
5.1 fatal: Authentication failed
这是最常见的问题。当你执行git clone遇到fatal: Authentication failed for 'https://github.com/...'时，可能的原因有：
- Token 复制错误，多了空格或者少了字符
- Token 已经过期
- 当前用户对该仓库没有访问权限
- 账号启用了两步验证，但用的不是 PAT，而是密码
- 仓库本身不存在，或者 URL 拼写有误
我的排查顺序是先确认 URL 语法，再看 token 是否能访问仓库：
git ls-remote https://x-access-token:${GITHUB_TOKEN}@github.com/myaccount/myproject.git如果上面命令能正常输出远端分支列表，说明认证和网络都没问题，问题可能出在本地仓库的状态上。如果输出还是有 error，那就能确认是 token 的问题。
5.2 remote: Repository not found
这种报错很容易让人以为是网站访问不了，但其实绝大多数情况是仓库名打错，或者当前 token 没有该仓库的访问权限。注意 GitHub 对不存在或没权限的仓库都统一返回Repository not found，这是出于安全考虑，避免泄露仓库是否存在。
这时候先检查仓库地址是否正确，再检查 token 权限里是否包含repo。
5.3 提示 “Support for password authentication was removed”
如果你用的 URL 还是https://用户名:密码@github.com/...，GitHub 会直接拒绝。解决办法就是换成 token，或者改用基于 token 的 URL。这个提示现在基本出现在老部署脚本或者某些教学文档里，注意看报错信息就能明白。
5.4 Token 明文泄露
很多人会把 token 写在部署脚本后，不小心提交到了公共仓库，或者打印到了 CI 日志里。一旦泄露，最好的办法是立即到 GitHub 后台删除该 token，然后创建一个新的替换掉。不要想着“反正还有别人也这样”，token 泄露就是事故，处理要果断。
可以在部署脚本里加一段日志脱敏的逻辑，避免打印 URL 时把 token 带出来：
echo "克隆中，仓库地址：${REPO_URL//${GITHUB_TOKEN}/***}"Shell 的${REPO_URL//${GITHUB_TOKEN}/***}会把 URL 中 token 部分替换成星号，这样日志里就不会出现敏感信息。
5.5 Token 过期导致定时任务失败
定时任务在凌晨执行部署时，如果 token 过期了，就会出现间歇性的拉取失败。因为 cron 环境通常不会加载你手动source的环境变量文件，所以你可能发现手动执行脚本没问题，但 cron 里就不行。
解决办法是把环境变量文件写到部署用户下，并在脚本开头显式 source：
source /home/deploy/.deploy_env或者在 systemd unit 里通过EnvironmentFile引入变量：
[Service] EnvironmentFile=/home/deploy/.deploy_env这样即使在 cron 或 systemd 环境下，token 也能正常加载。
5.6 常见问题速查表
| 报错信息 | 可能原因 | 解决办法 |
|---|---|---|
| fatal: Authentication failed | token 错误/过期/无权限 | 检查 token，确认 repo 权限 |
| remote: Repository not found | 仓库地址错误或权限不足 | 检查仓库 URL 和 token 权限 |
| Support for password authentication was removed | 使用了密码认证 | 改用 classic token |
| RPC failed; curl 56 OpenSSL SSL_read | 网络问题或文件过大 | 尝试浅克隆--depth=1，或分批次拉取 |
| could not read Username | 未配置 token 且仓库需要认证 | 在 URL 中注入 token 或配置 credential helper |
5.7 用 SSH 替代 Token 的场景
Token 并不是唯一的选择。如果你觉得自己长期维护同一台服务器，SSH key 方式可能更简单：把公钥添加到 GitHub 账号的 SSH keys 里，然后 clone 用git@github.com:用户名/仓库名.git，认证过程完全透明，不需要在 URL 中附带任何敏感信息。
但 SSH key 也有它的局限：
- 私钥一旦泄露，和 token 泄露一样危险
- 多台服务器就需要管理多个 key 对
- 在 CI 容器环境里，每次构建都要重新注入私钥，反而不如 token 方便
所以我现在的基本策略是：个人本地开发用 SSH，服务器和 CI 环境用 token。两者不冲突，按场景选择即可。
最后再分享两个小技巧
像 token 轮换这种操作，建议做一个固定流程。我一般会在手机日历上设置提醒，在 token 还有 15 天过期时就更新服务器上的环境变量文件，避免临时抱佛脚。如果你用的 CI 平台，记得把所有使用该 token 的项目都同步更新，漏掉一个可能就会出现构建失败。
还有一个容易被忽略的点：GitHub 生成的 token 只显示一次，但很多人会在浏览器里刷新页面，以为还能再看到。其实刷新之后页面就变成了 token 列表，无法查看具体值。如果忘了保存，只能重新生成一个，然后把之前用到的地方全部替换掉。因此，生成 token 后的第一个动作，永远是找一个安全的地方存下来。
