这里记录全流程，方便以后排查。

• python项目（爬虫网关）(采用 docker compose+SSH 脚本部署)
• go项目（算法平台)（由于云服务器内存限制，抛弃k8s，选择ssh）
• vue项目 面向用户平台（与后端共用一套compose，采用ssh）

在进行CI/CD项目之前，首先要确保 ci/cd 文件已配置完善。
并且拥有，可以部署的服务器。

python项目（爬虫网关）

打通从 GitHub 到服务器的自动化高速公路。

与我而言，这是最激动人心的时刻，但也是最容易卡壳的环节（通常卡在权限和配置上）。

1. 准备服务器环境

虽然 CI 脚本里有 mkdir，但有些关键文件 CI 是不会（也不应该）帮我创建的。所以此时我登录了我的服务器，手动做了一次初始化：

• 创建目录：

  mkdir -p /opt/crawler_center_scrapy
  

• 创建配置文件：
  把本地能跑通的 config.yaml 复制过去：

  vim /opt/crawler_center_scrapy/config.yaml
  # 粘贴你的配置内容
  

• 创建环境变量文件：
  如果有敏感信息（如 Token），写入 .env：

  vim /opt/crawler_center_scrapy/.env
  # 写入 INTERNAL_TOKEN=xxx 等
  

2. 生成密钥

最稳的做法就是， 在服务器上生成一对专用 key，把公钥放到服务器允许登录的位置，然后把私钥复制到 GitHub Secrets。

下面所有命令都可以直接复制粘贴执行。
注意：私钥内容千万不要发给任何人/粘贴到聊天里，只粘贴到 GitHub Secrets。

Step 0：确认你当前在服务器（ root目录下 ）

在服务器终端执行：

whoami
pwd

如果输出是 root 且路径类似 /root，继续。

Step 1：在服务器生成一对给 GitHub Actions 用的 SSH Key（无密码）

在服务器执行：

cd /root
ssh-keygen -t ed25519 -f /root/gh_actions_key -C "github-actions"

它会问：
Enter passphrase (empty for no passphrase):

直接回车两次（空密码）。

生成后你会有两个文件：

• /root/gh_actions_key（私钥）
• /root/gh_actions_key.pub（公钥）

检查一下：

ls -al /root/gh_actions_key*

Step 2：把公钥加入允许登录列表（authorized_keys）

在服务器执行：

mkdir -p /root/.ssh
chmod 700 /root/.ssh

cat /root/gh_actions_key.pub >> /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys

确认追加成功（会显示一行 ssh-ed25519 开头的内容）：

tail -n 1 /root/.ssh/authorized_keys

Step 3：验证这把私钥能 SSH 登录服务器（关键一步）

在服务器上可以“自己 ssh 自己”验证（不依赖你本地环境）：

先拿到本机公网 IP（如果你知道 IP 可跳过）

curl -s ifconfig.me || curl -s ipinfo.io/ip

假设输出是 1.2.3.4，那就在服务器执行：

ssh -i /root/gh_actions_key -o StrictHostKeyChecking=no root@1.2.3.4 "echo OK"

如果输出 OK，说明这把 key 没问题。
如果出问题了，那就粘给AI，让他帮你解决一下。

Step 4：获取要填到 GitHub Secrets 的内容

4.1 取服务器 IP（DEPLOY_HOST）

就是你服务器的公网 IP，比如 1.2.3.4（你自己知道或用上面 curl 得到）。

4.2 取用户名（DEPLOY_USER）

你现在是 root 登录，所以就是：
root

4.3 取私钥内容（DEPLOY_SSH_KEY）

在服务器执行：

cat /root/gh_actions_key

会输出一整段：
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

只需要把它复制，等会粘贴到 GitHub Secrets。

4.4（可选）取主机指纹（DEPLOY_HOST_FINGERPRINT）

在服务器执行：

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

它会输出类似：
256 SHA256:xxxxx root@xxx (ED25519)

你的 workflow 里 fingerprint: 字段有时需要的是 SHA256:xxxxx，有时需要的是 ssh-ed25519 AAAA...（不同版本 action 口径不完全一致）。

Step 5：去 GitHub 仓库里创建 Secrets（照点就行）

打开你的 GitHub 仓库页面，按路径点：
（别点错了，是你的项目仓库）

Settings → Secrets and variables → Actions → Secrets → New repository secret

依次创建这三个（先把必须的配好）：

5.1 创建 DEPLOY_HOST

• Name：DEPLOY_HOST
• Secret：填你的服务器公网 IP（如 1.2.3.4）

5.2 创建 DEPLOY_USER

• Name：DEPLOY_USER
• Secret：root

5.3 创建 DEPLOY_SSH_KEY

• Name：DEPLOY_SSH_KEY
• Secret：把刚才 cat /root/gh_actions_key 输出的整段私钥原样粘贴进去（包含 BEGIN/END 行）

（可选）如果你要加指纹，再创建：

• Name：DEPLOY_HOST_FINGERPRINT
• Secret：先留空也行；如果要填，按我下一条“验证失败再补”的方式最省事。

Step 6：创建 Variables（可选，但建议）

同页面：Settings → Secrets and variables → Actions → Variables → New repository variable

建议建：

• DEPLOY_PORT = 22
• DEPLOY_PATH = /opt/crawler_center_scrapy
• HEALTHCHECK_URL = http://127.0.0.1:8001/v2/healthz

（如果你的 workflow 里有默认值兜底，不建也能跑。）

Step 7：触发一次 workflow 验证

你已经有 workflow_dispatch，所以可以手动触发：

仓库 → Actions → 选择你的 CD - Build & Deploy → Run workflow。

看 deploy job 是否成功：

• 能连上服务器
• 能 docker compose pull/up
• 健康检查通过

step 8. 推送代码

配置好后，提交代码：

git add .
git commit -m "feat: setup full ci/cd pipeline"
git push origin main

step 9. 坐等收货

• 去 GitHub 仓库的 Actions 标签页。
• 你应该能看到两个 Workflow 正在跑：
  1. CI - Test (ci.yml)：很快就会绿。
  2. Release Image (release-image.yml)：跑完测试 -> 构建镜像 -> 部署上线。

go项目（算法平台）

本来是准备用k3s(k8s的瘦身版)，但是由于云空间不够了。所以退而，依然用ssh

这是一个从“代码提交”到“服务器自动上线”的完整闭环。请按照以下步骤，一步步来（我会告诉你每一步是做什么，以及为什么）。

因为本项目配置了 golangci-lint ，所以运行之初要记得：

golangci-lint run

第一阶段：服务器准备（只做一次）

首先再服务器把“窝”搭好，确保 CD 脚本跑过来的时候有地方落脚。

1. 登录 Linux 服务器。
2. 创建部署目录（对应我们改过的新名字）：

   mkdir -p /opt/assist-backed/static /opt/assist-backed/log
   

3. 上传生产环境配置：

   • 在服务器 /opt/assist-backed/ 目录下创建一个 .env 文件。
   • 把你自己本地 .env 里的内容复制进去（注意：记得把数据库 host 改成服务器能访问的地址，如果是 Docker 部署的 MySQL，可能不需要变；如果是云数据库，填内网 IP）。
   • 关键检查：确保 SYSTEM_PORT=8002，确保数据库密码正确。

nano /opt/assist-backed/.env

第二阶段：GitHub 仓库配置（只做一次）

我们需要把“钥匙”交给 GitHub Actions，让它能替你登录服务器和推镜像。

1. 打开你的 GitHub 仓库页面 -> Settings -> Secrets and variables -> Actions。

2. 点击 New repository secret，依次添加以下 7 个变量（请务必准确）：

   | Secret Name | 值 (Value) | 说明 |
   | :--- | :--- | :--- |
   | GHCR_PULL_USER | 你的 GitHub 用户名 (如 wdx-123) | 用于服务器拉取镜像 |
   | GHCR_PULL_TOKEN | 你的 GitHub Personal Access Token (PAT) | 必须有 read:packages 权限 |
   | SSH_HOST | 服务器 IP 地址 | Actions 连服务器用 |
   | SSH_PORT | 22 (或你的 SSH 端口) | 默认是 22 |
   | SSH_USER | root (或你的登录用户名) | 建议用 root 或有 docker 权限的用户 |
   | SSH_PRIVATE_KEY | 你的 SSH 私钥内容 | 也就是 ~/.ssh/id_rsa 的内容，全选复制，包含开头结尾 |
   | SSH_KNOWN_HOSTS | （见下方获取方法） | 防止中间人攻击 |

   如何获取 SSH_KNOWN_HOSTS？
   在你本地终端运行：ssh-keyscan -H <服务器IP>
   把输出的那几行全部复制进去。

第三阶段：本地提交与触发（每次发版）

配置都搞定后，以后你只需要做这一步：

1. 提交代码到 Git：

   git add .
   git commit -m "feat: complete ci/cd pipeline and rename project"
   git push origin main
   

   (注：如果现在不在 main 分支，记得先 merge 到 main)

2. 去 GitHub 看戏：

   • 点击仓库顶部的 Actions 标签。
   • 你会看到一个名为 cd-prod 的流水线正在跑。
   • 它会依次变绿：verify (检查代码) -> build_and_push (做镜像) -> deploy_prod (部署)。

第四阶段：验证结果

等 Actions 全绿之后：

1. 访问接口：
   打开浏览器或 Postman，访问：http://<服务器IP>:8002/api/v1/health
   • 预期返回：{"code":0, "data": {"status": "UP", ...}}
2. 服务器验证：
   在服务器上运行 docker ps，你应该能看到名为 assist-backed-app 的容器正在运行，且状态是 Up。

vue项目（面向用户平台）

在我的项目中，前端与后端共用一套compose，所以只需要在完善过ci-cd后。对github仓库完善仓库配置即可。
其他的操作，就与python项目与go项目一样了。
这种类型都是相通的😁。