添加 开发环境配置指南
@@ -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 节所述的大版本场景）。
|
||||
Reference in New Issue
Block a user