From e7e1d9fbfdb159019d5ab1aadc31b89a9f6f903a Mon Sep 17 00:00:00 2001 From: wang ze yao <2050409168@qq.com> Date: Fri, 30 May 2025 12:49:31 +0800 Subject: [PATCH] io --- docs/DevOps引擎/ci-config-validation.md | 85 +++++++++++++++++++ docs/DevOps引擎/代码流水线.md | 8 +- docs/DevOps引擎/引擎简介.md | 8 +- docs/intro/version-differences.md | 79 +++++++++++++++++ docs/代码库管理/WebIDE.md | 8 +- docs/代码库管理/repository-settings.md | 58 +++++++++++++ docs/代码库管理/template-repositories.md | 70 +++++++++++++++ docs/代码库管理/文件管理.md | 6 +- docs/合并请求/merge-request-guide.md | 64 ++++++++++++++ docs/快速开始/account-management.md | 38 +++++++++ docs/快速开始/keyboard-shortcuts.md | 41 +++++++++ docs/快速开始/webide.md | 29 +++++++ docs/疑修/issue-management.md | 55 ++++++++++++ docs/第三方服务/api-guide.md | 84 ++++++++++++++++++ 14 files changed, 626 insertions(+), 7 deletions(-) create mode 100644 docs/DevOps引擎/ci-config-validation.md create mode 100644 docs/intro/version-differences.md create mode 100644 docs/代码库管理/repository-settings.md create mode 100644 docs/代码库管理/template-repositories.md create mode 100644 docs/合并请求/merge-request-guide.md create mode 100644 docs/快速开始/account-management.md create mode 100644 docs/快速开始/keyboard-shortcuts.md create mode 100644 docs/快速开始/webide.md create mode 100644 docs/疑修/issue-management.md create mode 100644 docs/第三方服务/api-guide.md diff --git a/docs/DevOps引擎/ci-config-validation.md b/docs/DevOps引擎/ci-config-validation.md new file mode 100644 index 0000000..b21903f --- /dev/null +++ b/docs/DevOps引擎/ci-config-validation.md @@ -0,0 +1,85 @@ +# CI/CD配置文件校验指南 + +## 配置文件格式 +GitLink使用`.gitlink-ci.yml`作为CI/CD配置文件，提交时会自动进行语法校验。 + +## 校验规则 +1. **基本语法检查** + - YAML格式必须正确 + - 缩进必须使用2个空格 + - 不允许使用tab字符 + +2. **必需字段验证** + ```yaml + version: 1.0 # 必填，指定配置文件版本 + stages: # 必填，定义流水线阶段 + jobs: # 必填，定义具体任务 + ``` + +3. **字段类型验证** + - `version`: 字符串 + - `stages`: 数组 + - `jobs`: 对象 + - `script`: 字符串数组 + +4. **环境变量格式** + - 变量名只能包含字母、数字和下划线 + - 变量名必须以字母开头 + +## 错误提示说明 +当配置文件存在问题时，系统会在以下位置显示错误信息： +1. 提交时的即时反馈 +2. CI/CD页面的构建日志 +3. 合并请求的状态检查 + +## 常见错误及解决方案 +1. **缩进错误** + ```yaml + # 错误示例 + jobs: + build: # 应该缩进2个空格 + script: + - echo "Hello" + ``` + +2. **未定义必需字段** + ```yaml + # 正确示例 + version: 1.0 + stages: + - build + jobs: + build: + script: + - echo "Hello" + ``` + +3. **环境变量格式错误** + ```yaml + # 错误示例 + variables: + 1_invalid: "value" # 变量名不能以数字开头 + ``` + +## 配置文件模板 +```yaml +version: 1.0 +stages: + - build + - test + - deploy + +variables: + MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository" + +jobs: + build: + stage: build + script: + - mvn compile + + test: + stage: test + script: + - mvn test +``` \ No newline at end of file diff --git a/docs/DevOps引擎/代码流水线.md b/docs/DevOps引擎/代码流水线.md index 671fcd3..ad9f400 100644 --- a/docs/DevOps引擎/代码流水线.md +++ b/docs/DevOps引擎/代码流水线.md @@ -9,4 +9,10 @@ sidebar_position: 5 编辑流水线代码，其流水线名称描述、触发器、全局参数、执行串行/并发和流水线编排等概念同图形流水线，具体描述如下： -![code_workflow2](../../static/img/engine/code_workflow2.png) \ No newline at end of file +![code_workflow2](../../static/img/engine/code_workflow2.png) + +# YAML校验规则 +提交.gitlink-ci.yml时会自动校验以下内容： +- 必须包含version字段 +- 节点名称不能重复 +- 每个任务必须指定runner类型 \ No newline at end of file diff --git a/docs/DevOps引擎/引擎简介.md b/docs/DevOps引擎/引擎简介.md index e63549a..2ebc078 100644 --- a/docs/DevOps引擎/引擎简介.md +++ b/docs/DevOps引擎/引擎简介.md @@ -10,4 +10,10 @@ sidebar_position: 1 ![engine_intro](../../static/img/engine/engine_intro.jpg) -在引擎页面中，用户可以创建和编辑图形流水线或代码流水线、设置外部参数、管理密钥等操作。 \ No newline at end of file +在引擎页面中，用户可以创建和编辑图形流水线或代码流水线、设置外部参数、管理密钥等操作。 + +# 配置文件校验 +提交.gitlink-ci.yml文件时会自动进行语法校验，系统会提示以下常见错误： +- 无效的stage名称 +- 缺少必填字段 +- 语法格式错误 \ No newline at end of file diff --git a/docs/intro/version-differences.md b/docs/intro/version-differences.md new file mode 100644 index 0000000..027f1c4 --- /dev/null +++ b/docs/intro/version-differences.md @@ -0,0 +1,79 @@ +# GitLink版本功能对比 + +## 版本类型 + +### 社区版 +- 完全免费 +- 开源项目托管 +- 基础代码托管功能 +- 基础CI/CD功能 +- 公共仓库无限制 + +### 企业版 +- 收费服务 +- 私有部署 +- 高级功能支持 +- 专属技术支持 +- 自定义域名 + +## 功能对比表 + +| 功能 | 社区版 | 企业版 | +|------|--------|--------| +| 代码托管 | ✓ | ✓ | +| Issue管理 | ✓ | ✓ | +| Pull Request | ✓ | ✓ | +| WebHook | ✓ | ✓ | +| 基础CI/CD | ✓ | ✓ | +| Wiki | ✓ | ✓ | +| 公共仓库 | 无限制 | 无限制 | +| 私有仓库 | 限制数量 | 无限制 | +| 存储空间 | 1.2GB/仓库 | 可定制 | +| 团队成员 | 限制人数 | 无限制 | +| 审计日志 | ✗ | ✓ | +| LDAP集成 | ✗ | ✓ | +| SSO登录 | ✗ | ✓ | +| 高级CI/CD | ✗ | ✓ | +| 定制化服务 | ✗ | ✓ | +| 专属支持 | ✗ | ✓ | + +## 企业版专属功能 + +### 安全与合规 +- 审计日志 +- 合规检查 +- 安全扫描 +- 漏洞分析 + +### 身份认证 +- LDAP/AD集成 +- SSO登录 +- 双因素认证 +- 访问控制 + +### 高级DevOps +- 自定义CI/CD +- 容器镜像仓库 +- 制品库 +- 环境管理 + +### 团队协作 +- 项目组合管理 +- 高级权限控制 +- 工作流自动化 +- 团队数据分析 + +## 升级建议 +1. 适合升级企业版的场景： + - 需要私有部署 + - 要求更高安全性 + - 需要专业技术支持 + - 团队规模较大 + - 需要高级功能 + +2. 适合使用社区版的场景： + - 个人开发者 + - 小型团队 + - 开源项目 + - 基础代码托管需求 + - 预算有限 \ No newline at end of file diff --git a/docs/代码库管理/WebIDE.md b/docs/代码库管理/WebIDE.md index 33b3b06..6bd8608 100644 --- a/docs/代码库管理/WebIDE.md +++ b/docs/代码库管理/WebIDE.md @@ -35,7 +35,7 @@ sidebar_position: 9 ### **8. WebSCM** 可以在极速版新建分支，修改代码后在 SCM 面板看到变更文件列表，写完 commit message 后提交到 Gitlink 上。如果想快速修改一些文件可以不用在本地修改，直接通过极速版修改代码一次性提交。 -### **9. 代码在线运行** -● 集成了基于 skypack 的更加轻量的 CodeSwing 插件，可以在极速版去运行前端代码。 -● 集成了基于 Pyodide 的 Code-Runner-For-Web 插件，可以将 Python 的运行搬到浏览器上。 -![](../../static/img/代码库管理/WebIDE/WebIDE代码在线运行.png)
\ No newline at end of file +### **9. 快速访问方式** +在仓库文件列表页面，点击任意文件右侧的"编辑"按钮即可直接进入WebIDE界面。 + +![](../../static/img/代码库管理/WebIDE/快速访问入口.png) \ No newline at end of file diff --git a/docs/代码库管理/repository-settings.md b/docs/代码库管理/repository-settings.md new file mode 100644 index 0000000..f2f0f36 --- /dev/null +++ b/docs/代码库管理/repository-settings.md @@ -0,0 +1,58 @@ +# 仓库设置指南 + +## 强制推送（Force Push）设置 +要启用强制推送功能，需要同时满足以下条件： + +1. **用户权限要求** + - 必须是仓库管理员 + - 或具有特定分支的写入权限 + +2. **仓库设置要求** + - 进入仓库设置页面 + - 找到"分支保护"设置 + - 开启`allow_force_push`选项 + +### 配置步骤 +1. 进入仓库设置 +2. 选择"分支管理" +3. 找到目标分支 +4. 开启"允许强制推送"选项 +5. 保存设置 + +### 注意事项 +- 强制推送可能会覆盖其他人的提交 +- 建议在个人分支上使用 +- 不推荐在主分支上启用 +- 操作前先备份代码 + +## 仓库基本设置 + +### 仓库信息 +- 仓库名称 +- 仓库描述 +- 可见性设置 +- 默认分支 + +### 访问控制 +- 协作者管理 +- 团队权限 +- 分支保护规则 +- SSH密钥管理 + +### 功能开关 +- Issues功能 +- Wiki功能 +- Projects功能 +- Pages服务 + +## 存储限制 +- 免费账户：1.2GB +- 单文件上限：100MB +- LFS支持：可选开启 + +## 高级功能 +- 仓库迁移 +- 仓库归档 +- 仓库模板 +- WebHook配置 +- 部署密钥 \ No newline at end of file diff --git a/docs/代码库管理/template-repositories.md b/docs/代码库管理/template-repositories.md new file mode 100644 index 0000000..3475851 --- /dev/null +++ b/docs/代码库管理/template-repositories.md @@ -0,0 +1,70 @@ +# 仓库模板使用指南 + +## 访问模板仓库 +有两种方式可以访问模板仓库： + +1. **通过URL参数** + - 在仓库URL后添加`?template=true` + - 例如：`https://gitlink.org/org/repo?template=true` + +2. **通过界面入口** + - 点击"新建仓库"按钮 + - 选择"从模板创建"选项 + +## 创建模板仓库 + +### 将仓库设置为模板 +1. 进入仓库设置 +2. 找到"仓库类型"选项 +3. 勾选"将此仓库设置为模板" +4. 保存设置 + +### 模板仓库特性 +- 不能被直接推送代码 +- 可以被任何人用作模板 +- 保持干净的提交历史 +- 支持自定义初始化配置 + +## 使用模板创建仓库 + +### 基本步骤 +1. 访问模板仓库 +2. 点击"使用此模板"按钮 +3. 填写新仓库信息 +4. 选择要包含的分支 +5. 确认创建 + +### 自定义选项 +- 选择性复制分支 +- 包含所有标签 +- 复制Issue模板 +- 保留提交历史 + +## 最佳实践 + +### 模板仓库结构 +``` +template-repo/ +├── .gitlink/ +│ ├── ISSUE_TEMPLATE/ +│ └── PR_TEMPLATE/ +├── docs/ +│ └── README.md +├── src/ +├── tests/ +├── .gitignore +└── README.md +``` + +### 推荐配置 +1. 添加详细的README +2. 包含必要的配置文件 +3. 提供示例代码 +4. 设置Issue和PR模板 +5. 配置CI/CD模板 + +## 注意事项 +1. 模板仓库应保持最小化 +2. 定期更新模板内容 +3. 提供清晰的使用文档 +4. 避免包含敏感信息 \ No newline at end of file diff --git a/docs/代码库管理/文件管理.md b/docs/代码库管理/文件管理.md index bc03229..075a07d 100644 --- a/docs/代码库管理/文件管理.md +++ b/docs/代码库管理/文件管理.md @@ -16,4 +16,8 @@ sidebar_position: 4 ### **4. 编辑文件** 编辑界面右侧有三个按钮，分别是“下载”、“编辑”和“删除”，点击下载即可将文件下载到本地，编辑则可在线编辑文档，删除则将文件从代码库中删除，按钮位置如下图所示。 -![](../../static/img/代码库管理/文件管理/文件编辑按钮.png)
\ No newline at end of file +![](../../static/img/代码库管理/文件管理/文件编辑按钮.png)
+ +### **5. WebIDE在线编辑** +点击文件右侧的"编辑"按钮可直接进入WebIDE界面： +![](../../static/img/代码库管理/webide_entry.png) \ No newline at end of file diff --git a/docs/合并请求/merge-request-guide.md b/docs/合并请求/merge-request-guide.md new file mode 100644 index 0000000..576f9f5 --- /dev/null +++ b/docs/合并请求/merge-request-guide.md @@ -0,0 +1,64 @@ +# 合并请求使用指南 + +## 创建合并请求 + +### 基本步骤 +1. 进入源分支 +2. 点击"新建合并请求" +3. 选择目标分支 +4. 填写标题和描述 +5. 提交合并请求 + +## 审查合并请求 + +### 代码审查 +1. 查看变更文件 +2. 添加行内评论 +3. 提交整体评审意见 +4. 设置审查状态 + +### 合并操作 +1. 确保所有检查通过 +2. 滚动到评论框下方 +3. 找到"合并"按钮（位于评论区下方） +4. 选择合并方式 + - 普通合并 + - 压缩合并 + - 变基合并 + +## 合并选项说明 + +### 普通合并 +- 保留完整提交历史 +- 创建合并提交 +- 适合功能分支合并 + +### 压缩合并 +- 将所有提交压缩为一个 +- 保持主分支历史整洁 +- 适合bug修复合并 + +### 变基合并 +- 重放所有提交 +- 形成线性历史 +- 适合长期维护分支 + +## 最佳实践 + +### 提交合并请求前 +1. 确保本地测试通过 +2. 更新分支到最新 +3. 解决冲突 +4. 编写清晰的描述 + +### 审查要点 +1. 代码质量 +2. 测试覆盖 +3. 文档更新 +4. 性能影响 + +### 合并后操作 +1. 删除源分支 +2. 更新相关Issue状态 +3. 部署新版本（如需要） +4. 通知相关人员 \ No newline at end of file diff --git a/docs/快速开始/account-management.md b/docs/快速开始/account-management.md new file mode 100644 index 0000000..28e383c --- /dev/null +++ b/docs/快速开始/account-management.md @@ -0,0 +1,38 @@ +# 账户管理指南 + +## 登录方式 +GitLink提供多种便捷的登录方式： + +### 1. 账号密码登录 +- 使用注册邮箱/用户名 + 密码登录 +- 支持记住登录状态 + +### 2. 移动端扫码登录 +1. 在网页端登录界面点击"扫码登录" +2. 打开GitLink移动端APP +3. 点击APP右上角的扫码图标 +4. 扫描网页上显示的二维码 +5. 在手机上确认登录 + +### 3. 第三方账号登录 +- GitHub账号登录 +- GitLab账号登录 +- 微信登录 + +## 账户安全 +1. **二次验证** + - 支持Google Authenticator + - 支持手机验证码 + +2. **登录历史** + - 查看最近的登录记录 + - 显示登录IP和设备信息 + +3. **访问令牌** + - 创建个人访问令牌 + - 管理令牌权限和有效期 + +## 账户限制 +- 免费账户仓库存储限制：1.2GB +- 单个文件大小限制：100MB +- API调用频率限制：每小时1000次 \ No newline at end of file diff --git a/docs/快速开始/keyboard-shortcuts.md b/docs/快速开始/keyboard-shortcuts.md new file mode 100644 index 0000000..75314e4 --- /dev/null +++ b/docs/快速开始/keyboard-shortcuts.md @@ -0,0 +1,41 @@ +# 快捷键指南 + +## 全局快捷键 +- `shift + ?`: 显示快捷键帮助面板 +- `t`: 打开文件快速搜索 +- `s`: 聚焦搜索框 +- `g + c`: 跳转到代码页面 +- `g + i`: 跳转到Issues页面 +- `g + p`: 跳转到Pull Requests页面 + +## 代码浏览 +- `/`: 在当前仓库中搜索 +- `l`: 跳转到指定行 +- `b`: 查看文件历史 +- `y`: 复制永久链接 +- `i`: 显示/隐藏差异 + +## 代码编辑 +- `ctrl + s`: 保存更改 +- `ctrl + f`: 查找 +- `ctrl + g`: 跳转到行 +- `ctrl + /`: 注释/取消注释 +- `ctrl + space`: 触发代码补全 + +## Issue和PR +- `ctrl + enter`: 提交评论 +- `r`: 回复 +- `n`: 创建新Issue +- `m`: 设置里程碑 +- `l`: 添加标签 + +## 导航 +- `h`: 返回首页 +- `g + n`: 查看通知 +- `g + d`: 跳转到仪表盘 +- `g + s`: 跳转到设置 + +## 提示 +1. 在任何页面按下`shift + ?`可以查看当前页面支持的所有快捷键 +2. 部分快捷键在特定页面才能使用 +3. 快捷键可能会随平台更新而变化，请以帮助面板显示为准 \ No newline at end of file diff --git a/docs/快速开始/webide.md b/docs/快速开始/webide.md new file mode 100644 index 0000000..b21ad66 --- /dev/null +++ b/docs/快速开始/webide.md @@ -0,0 +1,29 @@ +# WebIDE使用指南 + +## 概述 +GitLink提供了强大的在线WebIDE功能，让您无需在本地安装开发环境即可直接在浏览器中编辑和运行代码。 + +## 如何访问WebIDE +1. 进入任意代码仓库 +2. 在文件列表界面，点击文件右侧的"编辑"按钮 +3. 系统将自动打开Cloud IDE界面 + +## 主要功能 +- 在线编辑代码 +- 实时语法高亮 +- 代码自动补全 +- 集成终端 +- 实时预览 +- 一键提交变更 + +## 快捷键支持 +WebIDE支持多种快捷键操作以提升开发效率： +- `Ctrl + S`: 保存文件 +- `Ctrl + F`: 在当前文件中搜索 +- `Ctrl + Shift + F`: 在项目中搜索 +- `F5`: 运行/调试 + +## 注意事项 +1. 首次打开WebIDE可能需要等待几秒钟进行环境初始化 +2. 建议使用Chrome或Firefox等现代浏览器以获得最佳体验 +3. 编辑完成后请及时提交更改 \ No newline at end of file diff --git a/docs/疑修/issue-management.md b/docs/疑修/issue-management.md new file mode 100644 index 0000000..ba87fe7 --- /dev/null +++ b/docs/疑修/issue-management.md @@ -0,0 +1,55 @@ +# Issue 管理指南 + +## Issue自动关闭 +GitLink支持通过提交信息自动关闭Issue。在提交信息中使用特定关键字，可以自动关闭相关Issue。 + +### 支持的关键字 +- `fix #123` +- `fixes #123` +- `fixed #123` +- `close #123` +- `closes #123` +- `closed #123` +- `resolve #123` +- `resolves #123` +- `resolved #123` + +### 使用示例 +``` +git commit -m "fix #123: 修复了登录按钮无响应的问题" +``` + +### 多Issue关闭 +可以在一条提交信息中关闭多个Issue： +``` +git commit -m "fix #123, closes #456: 重构登录模块" +``` + +### 跨仓库关闭 +可以通过指定完整路径关闭其他仓库的Issue： +``` +git commit -m "fix organization/repo#123: 修复依赖问题" +``` + +## 手动关闭Issue +1. 打开需要关闭的Issue +2. 点击右侧状态下拉菜单 +3. 选择"关闭Issue" +4. 可选：添加关闭原因说明 + +## Issue标签管理 +- 使用合适的标签分类Issue +- 可自定义标签颜色和描述 +- 支持批量编辑标签 + +## Issue模板 +1. 在仓库`.gitlink`目录下创建`ISSUE_TEMPLATE`文件夹 +2. 添加模板文件（支持markdown格式） +3. 新建Issue时可选择使用模板 + +## 最佳实践 +1. 使用清晰的标题描述问题 +2. 提供完整的复现步骤 +3. 附上相关的错误日志或截图 +4. 及时更新Issue状态 +5. 使用自动关闭语法关联提交和Issue \ No newline at end of file diff --git a/docs/第三方服务/api-guide.md b/docs/第三方服务/api-guide.md new file mode 100644 index 0000000..da226eb --- /dev/null +++ b/docs/第三方服务/api-guide.md @@ -0,0 +1,84 @@ +# API使用指南 + +## API响应格式 + +所有API响应都遵循以下统一格式： + +```json +{ + "code": 200, // 状态码 + "request_id": "xxx", // 请求唯一标识 + "data": { // 响应数据 + // 具体的业务数据 + } +} +``` + +### 状态码说明 +- 200: 请求成功 +- 400: 请求参数错误 +- 401: 未授权 +- 403: 禁止访问 +- 404: 资源不存在 +- 500: 服务器内部错误 + +### 重要说明 +1. `request_id`字段在每个响应中都会返回，用于问题追踪 +2. v2版本API已废弃，请使用v3版本 +3. 所有API调用都需要在Header中携带认证信息 + +## API版本说明 +- v3: 当前稳定版本（推荐使用） +- v2: 已废弃，返回410 Gone +- v1: 已移除 + +## 仓库相关API + +### 获取仓库信息 +```http +GET /api/v3/repos/{owner}/{repo} +``` + +响应示例： +```json +{ + "code": 200, + "request_id": "f58c7dd4-9876-4321-abcd-ef1234567890", + "data": { + "id": 12345, + "name": "example-repo", + "owner": { + "id": 67890, + "login": "example-user" + } + } +} +``` + +### 创建仓库 +```http +POST /api/v3/repos +``` + +请求体示例： +```json +{ + "name": "new-repo", + "description": "A new repository", + "private": false +} +``` + +## WebHook事件类型 +支持的事件类型包括： +1. `push`: 推送代码时触发 +2. `pull_request`: PR相关操作触发 +3. `issue`: Issue相关操作触发 +4. `release`: 发布版本时触发 +5. `star`: 加星操作触发 +6. `fork`: 仓库被fork时触发 +7. `comment`: 评论相关操作触发 +8. `repo_analytics`: 仓库统计数据更新时触发 +9. `wiki`: Wiki页面更新时触发 +10. `member`: 成员变更时触发 +11. `deploy`: 部署事件触发 \ No newline at end of file -- 2.34.1