From d7292e7e639408cc7338d3a4c45c6073aa5be7f0 Mon Sep 17 00:00:00 2001 From: SkyLiCoder Date: Mon, 13 Apr 2026 17:15:07 +0000 Subject: [PATCH] =?UTF-8?q?=E6=B7=BB=E5=8A=A0=20=E5=BC=80=E5=8F=91?= =?UTF-8?q?=E7=8E=AF=E5=A2=83=E9=85=8D=E7=BD=AE=E6=8C=87=E5=8D=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md | 403 ++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 %E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md diff --git a/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md b/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md new file mode 100644 index 0000000..336e494 --- /dev/null +++ b/%E5%BC%80%E5%8F%91%E7%8E%AF%E5%A2%83%E9%85%8D%E7%BD%AE%E6%8C%87%E5%8D%97.md @@ -0,0 +1,403 @@ +# 新成员开发环境配置指南 + +> 本文档面向团队新成员，指导如何配置开发环境、拉取代码并进行协作开发。 + +--- + +## 目录 + +1. [创建 SSH 公私钥对](#1-创建-ssh-公私钥对) +2. [在 Gitea 上添加公钥](#2-在-gitea-上添加公钥) +3. [验证 SSH 连接和签名验证](#3-验证-ssh-连接和签名验证) +4. [拉取主仓库及子模块](#4-拉取主仓库及子模块) +5. [开发流程](#5-开发流程) +6. [子模块更新说明](#6-子模块更新说明) + +--- + +## 1. 创建 SSH 公私钥对 + +如果没有现成的 SSH 密钥对，需要先生成一对。 + +### 生成命令 + +```bash +ssh-keygen -t ed25519 -C "your_email@example.com" +``` + +**参数说明：** +- `-t ed25519`：使用 Ed25519 算法（推荐，比 RSA 更安全、更短） +- `-C "your_email@example.com"`：注释，通常填你的邮箱，便于识别 + +### 交互提示 + +``` +Generating public/private ed25519 key pair. +Enter file in which to save key (/home/you/.ssh/id_ed25519): # 直接回车使用默认路径 +Enter passphrase (empty for no passphrase): # 输入密码短语，建议设置，若不设置则直接回车 +Enter same passphrase again: # 确认密码短语，若不设置则直接回车 +``` + +> **注意**：密码短语是你对私钥的额外保护，即使他人拿到私钥文件，没有密码也无法使用。请妥善保管，不要遗忘。 + +### 生成的文件 + +| 文件 | 说明 | +|------|------| +| `~/.ssh/id_ed25519` | 私钥（**不要泄露**） | +| `~/.ssh/id_ed25519.pub` | 公钥（需要填到 Gitea） | + +### 确认文件存在 + +```bash +ls -la ~/.ssh/id_ed25519* +``` + +--- + +## 2. 在 Gitea 上添加公钥 + +### 步骤 + +1. **获取公钥内容** + + ```bash + cat ~/.ssh/id_ed25519.pub + ``` + + 输出类似于： + ``` + ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBLABELOCATED/ahKwj98dsfsaf+ASDNo7your_email@example.com + ``` + +2. **登录 Gitea** + + 打开团队 Gitea 地址（如 `https://gitea.your-team.com`），登录你的账号。 + +3. **添加公钥** + + - 点击右上角头像 → **设置（Settings）** + - 左侧菜单找到 **SSH 密钥（SSH Keys）** + - 点击 **添加密钥（Add Key）** + - 填写： + - **标题（Title）**：给密钥起个名字，如 `我的笔记本` 或 `Desktop-PC` + - **密钥（Key）**：粘贴上一步 `cat` 输出的完整内容 + - 点击 **添加（Add Key）** + +--- + +## 3. 签名验证和验证 SSH 连接 + +### 签名验证 + +点开网页上的签名验证，在本地执行提示中的指令，形如： + +```bash +echo -n 'de8a6d7337894d506afe8a30759c54fe2c9afc0570f46891be94bf1f544cde43' | ssh-keygen -Y sign -n gitea -f ~/.ssh/id_ed25519 +``` + +输出示例： + +``` +-----BEGIN SSH SIGNATURE----- +U1NIU0lHAAAAA...（中间是一长串字符）... +-----END SSH SIGNATURE----- +``` + +将输出粘贴到网页中，点击验证即可。 + +这是因为，当前服务器已经拿到了你的公钥，服务器要确定你确实拥有对应的私钥，因此会给出一个随机字符串，让你运行以上命令使用你的私钥对这个字符串进行加密， +服务器拿到你的密文内容后，使用公钥对密文内容解密，将解密内容与一开始生成的字符串对比，如果一致，就说明你确实拥有私钥。 + +### 测试连接 + +```bash +ssh -T git@gitea.your-team.com +``` + +替换 `gitea.your-team.com` 为你们的 Gitea 域名。 + +**成功输出示例：** + +``` +Hi your_username! You've successfully authenticated, but Gitea does not provide shell access. +``` + +## 4. 拉取主仓库及子模块 + +### 克隆仓库 + +**必须使用 `--recursive` 参数**，否则子模块目录会是空的： + +```bash +git clone --recursive git@gitea.your-team.com:your-team/auto-aim-mobile-bot.git +``` + +### 如果克隆时忘记 `--recursive` + +可以单独初始化子模块： + +```bash +# 进入仓库目录 +cd auto-aim-mobile-bot + +# 初始化并更新子模块 +git submodule update --init --recursive +``` + +### 验证克隆结果 + +```bash +# 查看子模块状态 +git submodule status + +# 预期输出类似： +# 917f5b74eb6b1e8d7bce57fa2274bb0574f336b6 modules/chassis (heads/main) +# f9e81d6e04c2a38e43b78961aea2686aa121d960 modules/gimbal (heads/main) +``` + +--- + +## 5. 开发流程 + +### 5.1 创建新分支 + +**根据你要修改的目标，选择在对应仓库创建分支：** + +- **修改子模块**（`modules/chassis` 或 `modules/gimbal`）： + ```bash + cd modules/chassis # 进入子模块目录 + git checkout -b feature/your-feature-name + ``` +- **修改主仓库**（配置、文档等）： + ```bash + git checkout -b feature/your-feature-name # 在主仓库根目录执行 + ``` + +### 5.2 在子模块中开发 + +**进入子模块目录：** + +```bash +cd modules/chassis # 或 cd modules/gimbal +``` + +**创建子模块分支并开发：** + +```bash +git checkout -b feature/your-feature-name +# ... 进行开发，编写代码 ... +git add . +git commit -m "前缀: 描述你的改动" [-m "第一行" -m "第二行"] +# 多行内容推荐直接使用： +git commit +``` + +**推荐 commit message 格式：** + +``` +<类型>: <简短描述> + +[可选的详细说明] +``` + +**常用类型：** + +| 类型 | 含义 | +|------|------| +| `feat` | 新功能 | +| `fix` | 修复 bug | +| `docs` | 文档改动 | +| `style` | 代码格式（不影响功能） | +| `refactor` | 重构（不是修复也不是新功能） | +| `perf` | 性能优化 | +| `test` | 添加/修改测试 | +| `chore` | 构建/工具变动 | + +**示例：** + +``` +feat: 添加云台视觉识别模块 + +- 集成 YOLOv8 模型推理 +- 实现目标框坐标解算 +``` + +> 子模块和主仓库的 commit 均遵循此格式。 + +### 5.3 保持子模块代码最新 + +开发子模块时，**每次开始工作前**建议拉取最新代码，避免合并冲突： + +```bash +cd modules/chassis # 或 modules/gimbal +git checkout main +git pull origin main +git checkout feature/your-feature-name +git merge main # 或 git rebase main +``` + +或在主仓库一次性更新所有子模块到各自主分支的最新提交： + +```bash +git submodule update --remote --recursive +``` + +> **注意**：`--remote` 默认更新到各子模块的 `main` 分支。如果子模块有其他开发分支（如 `dev`），需要先在子模块内切换到对应分支，再单独 `git pull`。 + +### 5.4 提交主仓库（仅在需要时） + +> **重要提示**： +> +> 主仓库中记录的是**子模块当前指向的提交指针**。请**不要频繁提交**这类更新——每次子模块有新提交就提 PR 会造成大量噪音。 +> +> **只在以下情况才提交主仓库的子模块指针更新：** +> - 子模块有重大版本更新 +> - 需要同步所有成员的子模块状态 +> - release 准备阶段 + +**提交主仓库：** + +```bash +cd auto-aim-mobile-bot +git add modules/chassis modules/gimbal +git commit -m "chore: 更新子模块到最新版本" +``` + +### 5.5 推送分支 + +**推送子模块（如在子模块中开发）：** + +> 推送前请先确保你当前处于**子模块目录内**： + +```bash +cd modules/chassis # 或 modules/gimbal +git push -u origin feature/your-feature-name +``` + +> 注意：子模块的远程是独立的，push 操作不影响主仓库。推送后去对应的**子模块仓库**页面创建 PR。 + +**推送主仓库分支：** + +> 在主仓库**根目录**执行： + +```bash +git push -u origin feature/your-feature-name +``` + +### 5.6 提 Pull Request + +1. 在 Gitea 上打开对应的仓库页面 +2. 点击 **创建 Pull Request**（或 Compare & pull request） +3. 选择： + - **base branch**：合并目标分支（如 `main`） + - **compare branch**：你的开发分支（如 `feature/your-feature-name`） +4. 填写 PR 标题和描述，说明改动内容和目的 +5. 指定 Reviewer（如果有） +6. 点击 **创建 Pull Request** + +### 5.7 Review 通过后合并 + +- PR 通过 Review 后，点击 **Merge** +- 合并后**删除已合并的分支**（保持仓库整洁） + +--- + +## 6. 子模块更新说明 + +### 工作流程图 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 主仓库 (main) │ +│ 仅记录子模块指针，不频繁更新（仅大版本/发布前更新） │ +└─────────────────────────────────────────────────────────────┘ + ▲ ▲ ▲ + │ │ │ + │ submodule │ submodule │ submodule + │ update │ update │ update + │ --remote │ --remote │ --remote + │ │ │ +┌───────────┐ ┌───────────┐ ┌───────────┐ +│ chassis │ │ gimbal │ │ 其他模块 │ +│ (子模块) │ │ (子模块) │ │ (子模块) │ +│ 独立分支 │ │ 独立分支 │ │ 独立分支 │ +│ 独立PR │ │ 独立PR │ │ 独立PR │ +└───────────┘ └───────────┘ └───────────┘ +``` + +### 子模块独立开发的好处 + +- 各模块可以独立迭代，不影响其他模块 +- 子模块的 PR 不会触发主仓库不必要的构建 +- 团队可以并行开发多个功能 + +### 推荐做法 + +| 场景 | 操作位置 | +|------|---------| +| 修改 `modules/chassis` 代码 | 在 `modules/chassis` 目录内创建分支、提 PR | +| 修改 `modules/gimbal` 代码 | 在 `modules/gimbal` 目录内创建分支、提 PR | +| 修改主仓库配置/文档 | 在主仓库创建分支、提 PR | +| 更新子模块指针（仅大版本） | 在主仓库创建分支、提 PR | + +--- + +## 常见问题 + +### Q: 克隆时提示 `Permission denied (publickey)`？ + +检查： +1. 公钥是否正确添加到 Gitea +2. 私钥文件是否存在且权限正确（`chmod 600 ~/.ssh/id_ed25519`） +3. SSH 代理是否加载了私钥 + +### Q: 子模块目录是空的？ + +使用了 `git clone` 但没有加 `--recursive`，或子模块未初始化。运行： + +```bash +git submodule update --init --recursive +``` + +### Q: 如何查看子模块的远程地址？ + +```bash +git submodule foreach 'git remote -v' +``` + +### Q: 子模块当前在哪个分支？ + +进入子模块目录查看： + +```bash +cd modules/chassis +git branch +``` + +或在主仓库内查看所有子模块的当前分支状态： + +```bash +git submodule foreach 'git branch --show-current' +``` + +### Q: 能否在主仓库目录内直接操作子模块？ + +可以，使用 `git -C` 语法： + +```bash +git -C modules/chassis status +git -C modules/chassis checkout main +git -C modules/chassis pull origin main +``` + +这与先 `cd` 再执行效果相同。 + +### Q: 推送代码时需要同时推送主仓库和子模块吗？ + +不需要。**子模块和主仓库是独立的仓库**，各自有独立的提交历史和分支体系。 + +- 在子模块中开发 → 在子模块仓库提 PR → 合并到子模块的 main +- 在主仓库修改配置文件/文档 → 在主仓库提 PR → 合并到主仓库的 main + +**只有当你确实需要将子模块的指针更新同步给其他成员时**，才需要更新并推送主仓库（如第 5.4 节所述的大版本场景）。