AI 编程自动化部署文档

目录

1. [部署架构概述](#部署架构概述)
2. [腾讯工蜂 Git 仓库配置](#腾讯工蜂-git-仓库配置)
3. [SSH 密钥配置](#ssh-密钥配置)
4. [服务器环境准备](#服务器环境准备)
5. [宝塔面板Webhook脚本配置](#宝塔面板webhook脚本配置)
   1. 查看Webhook密钥
   2. 部署脚本
6. [Git 配置Webhook触发](#git-配置webhook触发)
   1. 腾讯工蜂网络回调钩子配置
   2. 秘密令牌说明
7. [部署验证](#部署验证)
8. [常见问题处理](#常见问题处理)

部署架构概述

┌─────────────────┐      push       ┌─────────────────┐
│  腾讯工蜂Git    │ ──────────────▶  │   宝塔Webhook   │
│  (代码仓库)     │                  │   (触发部署)    │
└─────────────────┘                  └────────┬────────┘
                                               │
                                               ▼
                                    ┌────────────────────┐
                                    │  部署脚本执行      │
                                    │  (拉取代码/安装    │
                                    │   依赖/重启服务)   │
                                    └────────┬───────────┘
                                             │
                    ┌────────────────────────┼────────────────────────┐
                    ▼                        ▼                        ▼
           ┌────────────────┐      ┌────────────────┐      ┌────────────────┐
           │   前端静态文件  │      │   PHP后端API   │      │    数据库      │
           │   (Nginx)      │      │   (PHP-FPM)    │      │   (MySQL)      │
           └────────────────┘      └────────────────┘      └────────────────┘

腾讯工蜂 Git 仓库配置

1. 创建仓库

1. 登录 腾讯工蜂
2. 点击「新建仓库」
3. 填写仓库信息：

2. 本地 Git 关联

# 进入项目目录
cd /your/local/project/path

# 初始化Git（如果尚未初始化）
git init

# 添加远程仓库地址
git remote add origin https://git.code.tencent.com/your-username/ai-tools-nav.git

# 或者如果已有关联，修改远程地址
git remote set-url origin https://git.code.tencent.com/your-username/ai-tools-nav.git

3. 推送代码到工蜂

# 添加所有文件
git add .

# 提交代码
git commit -m "Initial commit"

# 推送到远程仓库
git push -u origin master
# 或推送 main 分支
git push -u origin main

SSH 密钥配置

1. 生成 SSH 密钥

ssh-keygen -t rsa -C "your-description"

• 私钥：~/.ssh/id_rsa
• 公钥：~/.ssh/id_rsa.pub

2. 查看公钥

cat ~/.ssh/id_rsa.pub

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC6eNtGpNGwstc... your-description

3. 添加公钥到腾讯工蜂

1. 访问腾讯工蜂SSH密钥设置页面：https://git.code.tencent.com/profile/keys
2. 点击「添加 SSH 公钥」
3. 填写公钥信息：

4. 点击「添加」

4. 验证SSH连接

ssh -T git@git.code.tencent.com

Hi XXX! You've successfully authenticated, but Tencent does not provide shell access.

5. 修改 Git 仓库地址为 SSH 协议

# 查看当前远程仓库地址
git remote -v

# 修改为SSH地址
git remote set-url origin git@git.code.tencent.com:your-username/ai-tools-nav.git

6. SSH 连接常见问题解决

Unable to negotiate with 106.52.160.162 port 22: no matching host key type found. Their offer: ssh-rsa
fatal: Could not read from remote repository.

Host *
    HostkeyAlgorithms +ssh-rsa
    PubkeyAcceptedKeyTypes +ssh-rsa

服务器环境准备

1. 安装必要软件（宝塔面板）

2. 创建网站

1. 登录宝塔面板
2. 点击「网站」→「添加站点」
3. 配置信息：

• 域名：your-domain.com
• 根目录：/www/wwwroot/your-domain.com/frontend
• PHP版本：选择「纯静态」

• 域名：api.your-domain.com
• 根目录：/www/wwwroot/your-domain.com/backend
• PHP版本：7.4 或 8.0

3. 目录结构

/www/wwwroot/your-domain.com/
├── frontend/          # 前端文件（uniapp编译产物）
│   ├── pages/
│   ├── static/
│   ├── index.html
│   └── ...
├── backend/           # 后端PHP文件
│   ├── api/
│   ├── core/
│   ├── models/
│   ├── config/
│   └── index.php
└── deploy.log         # 部署日志

宝塔面板Webhook脚本配置

1. 安装Webhook插件

1. 登录宝塔面板
2. 点击「软件商店」→「搜索Webhook」
3. 安装「Webhook」插件

2. 创建Webhook

1. 点击「Webhook」→「添加Hook」
2. 配置信息：

3. 点击「确定」创建

3. 查看Webhook密钥

1. 找到刚创建的Hook
2. 点击「查看密钥」按钮
3. 弹出窗口显示：

密钥：xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

宝塔WebHook使用方法:
GET/POST:
https://your-server-ip:8888/hook?access_key=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

@param access_key string HOOK密钥
@param param string 自定义参数 (在hook脚本中使用$1接收)

• access_key 是宝塔Webhook的安全密钥，用于验证请求合法性
• 请妥善保管，不要泄露给他人
• 腾讯工蜂的「秘密令牌」应填写此 access_key

4. Webhook 部署脚本

#!/bin/bash

# ============================================
# AI工具导航站 - 自动部署脚本
# ============================================

# 配置变量
DEPLOY_PATH="/www/wwwroot/your-domain.com"
FRONTEND_PATH="$DEPLOY_PATH/frontend"
BACKEND_PATH="$DEPLOY_PATH/backend"
LOG_FILE="$DEPLOY_PATH/deploy.log"
GIT_REPO="https://git.code.tencent.com/your-username/ai-tools-nav.git"
BRANCH="master"

# 记录部署开始时间
echo "===========================================" >> $LOG_FILE
echo "部署开始时间: $(date '+%Y-%m-%d %H:%M:%S')" >> $LOG_FILE
echo "===========================================" >> $LOG_FILE

# 进入部署目录
cd $DEPLOY_PATH || exit 1

# 拉取最新代码
echo "正在拉取最新代码..." >> $LOG_FILE
git fetch --all >> $LOG_FILE 2>&1
git reset --hard origin/$BRANCH >> $LOG_FILE 2>&1

# 判断拉取结果
if [ $? -eq 0 ]; then
    echo "代码拉取成功" >> $LOG_FILE
else
    echo "代码拉取失败" >> $LOG_FILE
    exit 1
fi

# 前端构建（如果需要）
if [ -d "$FRONTEND_PATH" ] && [ -f "$FRONTEND_PATH/package.json" ]; then
    echo "开始构建前端..." >> $LOG_FILE
    cd $FRONTEND_PATH
    
    # 检查并安装依赖（可选，根据项目需求）
    # if [ -f "package-lock.json" ]; then
    #     npm install >> $LOG_FILE 2>&1
    # fi
    
    # 如果是uniapp项目，需要编译
    # npm run build >> $LOG_FILE 2>&1
    
    echo "前端处理完成" >> $LOG_FILE
fi

# 后端权限设置
if [ -d "$BACKEND_PATH" ]; then
    echo "设置后端目录权限..." >> $LOG_FILE
    chown -R www:www $BACKEND_PATH
    chmod -R 755 $BACKEND_PATH
    chmod -R 777 $BACKEND_PATH/runtime 2>/dev/null || true
fi

# 前端权限设置
if [ -d "$FRONTEND_PATH" ]; then
    echo "设置前端目录权限..." >> $LOG_FILE
    chown -R www:www $FRONTEND_PATH
    chmod -R 755 $FRONTEND_PATH
fi

# 重启PHP服务（如需要）
echo "尝试重启PHP服务..." >> $LOG_FILE
systemctl restart php-fpm-74 2>/dev/null || true

# 部署完成
echo "部署完成时间: $(date '+%Y-%m-%d %H:%M:%S')" >> $LOG_FILE
echo "===========================================" >> $LOG_FILE
echo "" >> $LOG_FILE

# 返回成功信息
echo "部署成功"
exit 0

Git 配置Webhook触发

方式一：腾讯工蜂 Webhook（推荐）

配置项说明

配置步骤

1. 进入腾讯工蜂仓库页面
2. 点击左侧「设置」菜单
3. 选择「高级设置」标签
4. 选择「网络回调钩子」子选项
5. 点击「创建网络回调钩子」按钮
6. 填写配置信息：

┌─────────────────────────────────────────────────────────┐
│  网络回调钩子配置界面                                    │
├─────────────────────────────────────────────────────────┤
│  Url                                                    │
│  ┌─────────────────────────────────────────────────┐   │
│  │ https://your-server-ip:8888/hook?access_key=xxx │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  秘密令牌                                               │
│  ┌─────────────────────────────────────────────────┐   │
│  │ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx               │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  触发器                                                 │
│  ◉ 推送事件     当有版本库推送时，该URL将被触发        │
│  ○ 标签推送事件                                         │
│  ○ 评论事件                                             │
│  ○ 议题事件                                             │
│  ○ 合并请求事件                                         │
│  ○ 评审事件                                             │
│                                                         │
│           [  创建网络回调钩子  ]                         │
└─────────────────────────────────────────────────────────┘

7. 点击「创建网络回调钩子」保存

安全说明

• 腾讯工蜂会在请求头中添加 X-Gitlab-Token 或类似字段携带此令牌
• 宝塔Webhook会自动校验 access_key 参数
• 确保宝塔的 access_key 与工蜂的「秘密令牌」一致

方式二：本地Git钩子（备选）

# 在本地仓库创建post-receive钩子
cat > .git/hooks/post-receive << 'EOF'
#!/bin/bash

WEBHOOK_URL="https://your-server-ip:8888/hook?token=xxxxxxxxxxxxx"

while read oldrev newrev refname; do
    branch=$(echo $refname | sed 's/refs\/heads\///')
    if [ "$branch" == "master" ] || [ "$branch" == "main" ]; then
        curl -s "$WEBHOOK_URL"
    fi
done
EOF

# 设置执行权限
chmod +x .git/hooks/post-receive

部署验证

1. 手动测试

https://your-server-ip:8888/hook?token=xxxxxxxxxxxxx

2. 自动测试

1. 修改本地代码
2. 提交并推送到腾讯工蜂
3. 在服务器上查看部署日志：

tail -f /www/wwwroot/your-domain.com/deploy.log

3. 验证网站

• 访问前端：https://your-domain.com
• 访问后端：https://api.your-domain.com

常见问题处理

问题1：Webhook无法访问

# 开放8888端口（宝塔环境）
firewall-cmd --permanent --add-port=8888/tcp
firewall-cmd --reload

问题2：Git拉取失败

git config --global credential.helper store
# 首次拉取时输入用户名密码

问题3：权限问题

chown -R www:www /www/wwwroot/your-domain.com
chmod -R 755 /www/wwwroot/your-domain.com

问题4：PHP服务未重启

# PHP 7.4
systemctl restart php-fpm-74

# PHP 8.0
systemctl restart php-fpm-80

问题5：数据库连接失败

问题6：Webhook 403 认证失败

1. 在宝塔Webhook中查看正确的 access_key
2. 在腾讯工蜂「网络回调钩子」的「秘密令牌」字段填入相同的值
3. 确保URL中的 access_key 参数与秘密令牌一致

问题7：宝塔Webhook测试成功但工蜂推送不触发

1. 检查宝塔Webhook日志，查看接收到的请求参数
2. 确认URL格式正确：https://ip:8888/hook?access_key=xxx
3. 检查服务器防火墙是否允许来自腾讯工蜂的请求

部署流程图

┌─────────────┐
│  开发人员    │
│  提交代码    │
└──────┬──────┘
       │ git push
       ▼
┌─────────────┐
│  腾讯工蜂    │
│  触发Webhook│
└──────┬──────┘
       │ HTTP请求
       ▼
┌─────────────┐
│  宝塔Webhook│
│  执行部署脚本│
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  1.拉取代码 │
│  2.构建前端 │
│  3.设置权限 │
│  4.重启服务 │
└──────┬──────┘
       │
       ▼
┌─────────────┐
│  部署完成    │
│  网站可访问  │
└─────────────┘

配置清单

联系方式

1. 部署日志：/www/wwwroot/your-domain.com/deploy.log
2. 宝塔面板日志
3. Nginx错误日志