slms/docs/JENKINS_CONFIGURATION_GUIDE.md

Jenkins 任务配置更新指南

目的: 更新 Jenkins 任务配置以使用新的仓库结构和本地 Gitea

---

前提条件

1. ✅ Jenkinsfile 已更新（任务 2-14 已完成）
2. ✅ 代码已推送到本地 Gitea（任务 17 已完成）
3. ✅ Jenkins 服务正在运行: http://localhost:8080

---

方法 1: 通过 Jenkins Web UI 更新

步骤 1: 访问 Jenkins

1. 打开浏览器访问: http://localhost:8080
2. 登录 Jenkins

步骤 2: 找到 SLMS 任务

1. 在 Jenkins 首页找到 SLMS 项目
2. 或访问: http://localhost:8080/job/SLMS/

步骤 3: 配置任务

1. 点击左侧 Configure (配置)
2. 找到 Source Code Management (源代码管理) 部分

步骤 4: 更新 Git 配置

4.1 更新仓库 URL

Repository URL:

http://localhost:3000/gitea/slms.git

4.2 配置凭据

Credentials:

• 选择 gitea-credentials
• 如果不存在，点击 Add 创建:
  • Kind: Username with password
  • Username: Gitea 用户名
  • Password: Gitea 密码
  • ID: gitea-credentials
  • Description: Gitea Credentials

4.3 配置分支

Branches to build:

*/main

4.4 配置浅克隆（可选）

在 Additional Behaviours 部分:

1. 点击 Add → Advanced clone behaviours
2. 配置:
   • ✅ Shallow clone
   • Shallow clone depth: 1
   • ✅ Honor refspec on initial clone

或者:

1. 点击 Add → Clone extensions
2. 配置:
   • ✅ Shallow clone
   • Depth: 1
   • ✅ No tags

步骤 5: 验证头歌凭据

1. 在 Jenkins 首页点击 Manage Jenkins
2. 点击 Manage Credentials
3. 找到 educoder-credentials
4. 如果不存在，创建:
   • Kind: Username with password
   • Username: 头歌用户名
   • Password: 头歌密码
   • ID: educoder-credentials
   • Description: Educoder Credentials

步骤 6: 保存配置

1. 滚动到页面底部
2. 点击 Save 保存配置

步骤 7: 测试配置

1. 点击左侧 Build Now (立即构建)
2. 观察构建过程
3. 检查 Console Output (控制台输出)

---

方法 2: 通过 Jenkins Configuration as Code (JCasC)

创建 JCasC 配置文件

创建文件 jenkins.yaml:

credentials:
  system:
    domainCredentials:
      - credentials:
          - usernamePassword:
              scope: GLOBAL
              id: "gitea-credentials"
              username: "your-gitea-username"
              password: "your-gitea-password"
              description: "Gitea Credentials"
          - usernamePassword:
              scope: GLOBAL
              id: "educoder-credentials"
              username: "your-educoder-username"
              password: "your-educoder-password"
              description: "Educoder Credentials"

jobs:
  - script: >
      pipelineJob('SLMS') {
        definition {
          cpsScm {
            scm {
              git {
                remote {
                  url('http://localhost:3000/gitea/slms.git')
                  credentials('gitea-credentials')
                }
                branches('*/main')
                extensions {
                  cloneOptions {
                    shallow(true)
                    depth(1)
                    noTags(true)
                  }
                }
              }
            }
            scriptPath('Jenkinsfile')
          }
        }
      }      

应用配置

1. 将 jenkins.yaml 放在 Jenkins 配置目录
2. 重启 Jenkins 或重新加载配置

---

方法 3: 通过 Jenkins CLI

前提条件

下载 Jenkins CLI:

curl -O http://localhost:8080/jnlpJars/jenkins-cli.jar

导出当前配置

java -jar jenkins-cli.jar -s http://localhost:8080/ -auth USER:TOKEN get-job SLMS > slms-job.xml

编辑配置文件

在 slms-job.xml 中找到并更新:

<scm class="hudson.plugins.git.GitSCM">
  <userRemoteConfigs>
    <hudson.plugins.git.UserRemoteConfig>
      <url>http://localhost:3000/gitea/slms.git</url>
      <credentialsId>gitea-credentials</credentialsId>
    </hudson.plugins.git.UserRemoteConfig>
  </userRemoteConfigs>
  <branches>
    <hudson.plugins.git.BranchSpec>
      <name>*/main</name>
    </hudson.plugins.git.BranchSpec>
  </branches>
  <extensions>
    <hudson.plugins.git.extensions.impl.CloneOption>
      <shallow>true</shallow>
      <noTags>true</noTags>
      <depth>1</depth>
    </hudson.plugins.git.extensions.impl.CloneOption>
  </extensions>
</scm>

更新任务配置

java -jar jenkins-cli.jar -s http://localhost:8080/ -auth USER:TOKEN update-job SLMS < slms-job.xml

---

验证配置

1. 检查 SCM 配置

1. 访问任务配置页面
2. 确认:
   • ✅ Repository URL: http://localhost:3000/gitea/slms.git
   • ✅ Credentials: gitea-credentials
   • ✅ Branch: */main
   • ✅ Shallow clone: 已启用

2. 测试代码拉取

1. 点击 Build Now
2. 查看 Console Output
3. 检查拉取时间是否 < 2 分钟
4. 确认没有 SLMS/ 子目录相关错误

3. 检查凭据

访问: http://localhost:8080/credentials/

确认存在:

• ✅ gitea-credentials - 本地 Gitea 访问
• ✅ educoder-credentials - 头歌访问
• ✅ sonarqube-token - SonarQube 访问（如果使用）

---

配置检查清单

完成以下检查以确保配置正确:

• Jenkins 服务正在运行
• SLMS 任务已创建或更新
• SCM 仓库 URL 为 http://localhost:3000/gitea/slms.git
• 分支配置为 */main
• gitea-credentials 凭据已配置
• educoder-credentials 凭据已配置
• 浅克隆选项已启用（可选但推荐）
• Jenkinsfile 路径正确（默认为根目录）
• 测试构建能够成功拉取代码

---

常见问题

Q1: 找不到 gitea-credentials

A:

1. 访问: http://localhost:8080/credentials/
2. 点击 Add Credentials
3. 创建新的用户名密码凭据
4. ID 设置为 gitea-credentials

Q2: 代码拉取失败 - 认证错误

A:

1. 检查 Gitea 用户名和密码是否正确
2. 确认 Gitea 服务正在运行
3. 测试手动克隆: git clone http://localhost:3000/gitea/slms.git

Q3: 代码拉取失败 - 仓库不存在

A:

1. 确认仓库已在 Gitea 中创建
2. 访问: http://localhost:3000/gitea/slms
3. 检查仓库 URL 是否正确

Q4: 浅克隆选项不可用

A:

1. 确认 Git 插件版本 >= 4.0
2. 更新 Jenkins 插件
3. 或在 Jenkinsfile 中配置浅克隆（已完成）

Q5: 构建失败 - 找不到 Jenkinsfile

A:

1. 确认 Jenkinsfile 在仓库根目录
2. 检查文件名大小写（应为 Jenkinsfile）
3. 确认文件已推送到 Gitea

---

性能优化建议

1. 启用浅克隆

减少代码拉取时间从几十分钟到 2 分钟以内。

2. 配置 Git 缓存

在 Jenkins 节点上:

git config --global http.postBuffer 524288000
git config --global core.compression 0

3. 使用本地 Gitea

相比外部仓库，本地 Gitea 速度更快。

4. 定期清理工作空间

在 Jenkinsfile 中使用 CleanBeforeCheckout 和 CleanCheckout。

---

下一步

完成 Jenkins 配置后:

1. ✅ 测试完整流水线（任务 20）
2. ✅ 验证和文档更新（任务 21）

---

相关脚本:

• scripts/check_jenkins_config.bat - 检查 Jenkins 配置
• scripts/test_jenkins_build.bat - 测试 Jenkins 构建

相关文档:

• Jenkinsfile (已更新)
• .kiro/specs/repository-restructure/design.md