【环境搭建】Windows 10上使用Docker搭建本地Git仓库（Gitea）完整教程

在Windows 10上使用Docker搭建本地Git仓库（Gitea）完整教程

引言
[第一部分：准备工作------安装Docker Desktop](#第一部分：准备工作——安装Docker Desktop)
- [1.1 检查系统要求](#1.1 检查系统要求)
- [1.2 安装Docker Desktop](#1.2 安装Docker Desktop)
- [1.3 验证安装](#1.3 验证安装)
- [1.4 配置镜像加速（可选但推荐）](#1.4 配置镜像加速（可选但推荐）)
第二部分：选择Git仓库方案
第三部分：使用Docker安装Gitea
- [3.1 创建项目目录](#3.1 创建项目目录)
- [3.2 编写docker-compose.yml](#3.2 编写docker-compose.yml)
- [3.3 启动Gitea容器](#3.3 启动Gitea容器)
- [3.4 完成首次Web安装配置](#3.4 完成首次Web安装配置)
- [3.5 创建第一个用户和仓库](#3.5 创建第一个用户和仓库)
第四部分：测试使用Git仓库
- [4.1 HTTP方式克隆和推送](#4.1 HTTP方式克隆和推送)
- [4.2 SSH方式配置和使用](#4.2 SSH方式配置和使用)
第五部分：常见问题与解决方案
- [5.1 问题：git push时 "src refspec main does not match any"](#5.1 问题：git push时 “src refspec main does not match any”)
- [5.2 问题：SSH连接 refused（port 22）](#5.2 问题：SSH连接 refused（port 22）)
- [5.3 其他可能问题](#5.3 其他可能问题)
第六部分：日常维护
- [6.1 启动/停止Gitea](#6.1 启动/停止Gitea)
- [6.2 备份数据](#6.2 备份数据)
- [6.3 升级Gitea](#6.3 升级Gitea)
结语

引言

作为一名开发者，拥有一个属于自己的Git仓库来管理代码是非常必要的。虽然可以使用GitHub、GitLab等公共服务，但有时我们希望将代码完全掌控在自己手中，或者需要一个本地仓库进行快速测试。本文将详细介绍如何在Windows 10上使用Docker搭建一个轻量级的本地Git仓库------Gitea。整个过程简单、资源占用小，非常适合个人开发者或小型团队。

第一部分：准备工作------安装Docker Desktop

在开始搭建Gitea之前，我们需要先安装Docker Desktop，因为我们将使用容器运行Gitea。

1.1 检查系统要求

操作系统：Windows 10 64位专业版、企业版或教育版（Build 15063或更高）。
CPU虚拟化：需要在BIOS中开启（Intel VT-x / AMD-V）。可以在任务管理器的"性能"选项卡中查看"虚拟化"是否已启用。
内存：至少4GB（推荐8GB以上）。
WSL 2 ：推荐启用，以获得更好的性能。以管理员身份打开PowerShell，执行以下命令并重启：
powershell 复制代码
```
wsl --install
```

1.2 安装Docker Desktop

访问Docker Desktop官方下载页面，下载Windows版本的安装程序。
双击运行安装程序，在配置界面勾选 "Use WSL 2 instead of Hyper-V"（推荐），然后点击"OK"。
安装完成后，按照提示重启电脑。

1.3 验证安装

重启后，Docker Desktop会自动启动。打开PowerShell或命令提示符，执行：

bash 复制代码

docker --version

如果显示类似 Docker version 27.3.1, build 41b3b25 的信息，说明安装成功。

再运行一个测试容器：

bash 复制代码

docker run hello-world

如果看到欢迎信息，说明Docker可以正常工作。

1.4 配置镜像加速（可选但推荐）

由于网络原因，国内用户拉取镜像可能较慢。可以配置国内镜像加速器（如中科大、阿里云等）。在Docker Desktop设置中，找到 Docker Engine 选项卡，添加如下配置：

json 复制代码

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

点击 "Apply & Restart" 保存。

第二部分：选择Git仓库方案

目前主流的自托管Git仓库方案有 Gitea 和 GitLab。它们的对比如下：

特性	Gitea	GitLab CE
资源占用	极低（几百MB内存）	较高（建议4GB+内存）
功能	专注核心Git功能，界面清爽	功能全面，内置CI/CD、容器镜像仓库等
适合场景	个人开发者、小型团队	追求一站式DevOps体验的团队
上手难度	简单	稍复杂

考虑到Windows 10的资源限制和易用性，本文选择 Gitea 作为本地Git仓库。

第三部分：使用Docker安装Gitea

3.1 创建项目目录

在Windows上创建一个目录用于存放Gitea的数据，例如 C:\docker\gitea。打开PowerShell执行：

powershell 复制代码

mkdir C:\docker\gitea -Force
cd C:\docker\gitea

3.2 编写docker-compose.yml

在 C:\docker\gitea 目录下创建 docker-compose.yml 文件，内容如下：

yaml 复制代码

version: "3"
services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"      # Web访问端口
      - "222:22"         # SSH端口（映射到宿主机的222端口，避免冲突）

注意：SSH端口映射为222，是为了避免和Windows自带的SSH服务（默认22端口）冲突。

3.3 启动Gitea容器

在PowerShell中执行：

bash 复制代码

docker-compose up -d

等待容器启动完成后，可以通过以下命令查看容器状态：

bash 复制代码

docker ps

确保 gitea 容器的状态为 Up。

3.4 完成首次Web安装配置

打开浏览器，访问 http://localhost:3000。
进入Gitea的安装页面，关键配置如下：
- 数据库设置 ：选择 SQLite3（最简单，无需额外数据库）。
- 站点名称：随意填写，如 "My Git Repo"。
- SSH服务端口 ：填写 22（注意：这是容器内部的22端口，映射到宿主机的222端口）。
- 基础URL ：填写 http://localhost:3000。
- 管理员账号设置：可以跳过，稍后创建第一个用户会自动成为管理员。
- 其他设置：根据个人需求勾选"禁止自助注册"等。
点击 "立即安装"，等待几秒钟完成配置。

3.5 创建第一个用户和仓库

安装完成后，会跳转到登录页面。点击 "立即注册"，创建第一个用户（该用户将成为管理员）。
登录后，点击右上角的 "+" → "新建仓库"。
填写仓库名称（例如 my-first-project），选择公开或私有，点击 "创建仓库"。

第四部分：测试使用Git仓库

4.1 HTTP方式克隆和推送

HTTP方式最简单，无需配置SSH。在本地任意目录打开PowerShell，执行：

bash 复制代码

# 克隆仓库（替换 yourusername 为你的用户名）
git clone http://localhost:3000/你的用户名/my-first-project.git
cd my-first-project

# 创建一个测试文件
echo "# My First Project" > README.md

# 提交并推送
git add README.md
git commit -m "第一次提交"
git push

推送时会提示输入Gitea的用户名和密码，输入即可。

4.2 SSH方式配置和使用

使用SSH可以避免每次推送输入密码，但需要额外配置。

生成SSH密钥（如果还没有）

bash 复制代码

ssh-keygen -t rsa -b 4096 -C "你的邮箱@example.com"

一路回车，将在 C:\Users\你的用户名\.ssh\ 下生成 id_rsa（私钥）和 id_rsa.pub（公钥）。

在Gitea中添加公钥

登录Gitea，点击右上角头像 → 设置 → SSH / GPG 密钥。
在"添加密钥"区域，将 id_rsa.pub 文件的内容完整复制进去，点击"增加密钥"。

测试SSH连接

bash 复制代码

ssh -p 222 git@localhost

如果看到欢迎信息 Hi there, You've successfully authenticated...，说明SSH配置成功。

使用SSH方式克隆和推送

bash 复制代码

# 克隆仓库（注意端口是222）
git clone ssh://git@localhost:222/你的用户名/my-first-project.git
cd my-first-project

# 进行一些修改后推送
git push

第五部分：常见问题与解决方案

5.1 问题：git push时 "src refspec main does not match any"

现象：执行 git push -u origin main 时提示错误 error: src refspec main does not match any。

原因：本地仓库还没有任何提交（commit），或者默认分支名称不是 main（可能是 master）。

解决方案：

检查本地分支名称：
bash 复制代码
```
git branch
```
如果显示 * master，说明默认分支是 master，可以推送 master 分支：
bash 复制代码
```
git push -u origin master
```
或者将本地分支重命名为 main：
bash 复制代码
```
git branch -m master main
git push -u origin main
```

如果是空仓库，先创建一次提交：

bash 复制代码

echo "# My Project" > README.md
git add README.md
git commit -m "Initial commit"
git push -u origin main   # 或 master

5.2 问题：SSH连接 refused（port 22）

现象：执行 git push 时报错 ssh: connect to host localhost port 22: Connection refused。

原因：我们配置Gitea时将SSH映射到了宿主机的222端口，但Git远程地址仍然使用默认的22端口。

解决方案：

方法一 ：修改远程仓库地址，指定正确的SSH端口：
bash 复制代码
```
git remote set-url origin ssh://git@localhost:222/你的用户名/仓库名.git
```

方法二 ：改用HTTP方式（最简单）：

bash 复制代码

git remote set-url origin http://localhost:3000/你的用户名/仓库名.git

方法三 ：配置SSH config文件（推荐经常使用SSH的用户）：
编辑 ~/.ssh/config，添加：
复制代码
```
Host gitea-local
    HostName localhost
    Port 222
    User git
```
然后修改远程地址：
bash 复制代码
```
git remote set-url origin gitea-local:你的用户名/仓库名.git
```

5.3 其他可能问题

端口3000被占用 ：修改 docker-compose.yml 中的 "3000:3000" 为其他端口（如 "3001:3000"），然后重新 docker-compose up -d。
防火墙阻止：检查Windows防火墙是否允许Docker使用的端口，可以临时关闭防火墙测试。
权限问题：如果推送时遇到权限错误，确认在Gitea中正确添加了SSH公钥，或者HTTP方式输入了正确的用户名密码。

第六部分：日常维护

6.1 启动/停止Gitea

进入Gitea目录（C:\docker\gitea），执行：

bash 复制代码

# 停止容器（数据不会丢失）
docker-compose stop

# 重新启动
docker-compose start

# 彻底删除容器（数据保留在卷中）
docker-compose down

6.2 备份数据

Gitea的所有数据（仓库、数据库、配置）都保存在 C:\docker\gitea\gitea 文件夹中。定期备份该文件夹即可。

6.3 升级Gitea

bash 复制代码

cd C:\docker\gitea
docker-compose pull gitea      # 拉取最新镜像
docker-compose up -d           # 重新创建容器

结语

至此，你已经成功在Windows 10上使用Docker搭建了一个属于自己的本地Git仓库------Gitea。它轻量、快速，并且完全由你掌控。无论是个人项目练习，还是团队内部协作，Gitea都能很好地满足需求。如果在使用过程中遇到其他问题，欢迎在评论区留言交流。

Happy Coding! 🚀