当前位置：首页 > news >正文

阿里云 Windows 服务器搭建 Gitea 私有 Git 服务器完整教程

news 2025/8/13 5:30:13

Windows 系统搭建 Gitea 私有 Git 服务器完整教程

本文详细介绍如何在 Windows 系统上搭建 Gitea 私有 Git 服务器，包含完整的环境配置、安装步骤、常见问题解决方案，适合个人开发者和小团队使用。

📝 前言

在日常开发中，搭建私有 Git 服务器是许多开发者和团队的需求。相比于 GitLab 的复杂配置，Gitea 是一个轻量级的 Git 服务解决方案。本文将详细介绍在阿里云 Windows 服务器上搭建 Gitea 服务器的完整过程，并重点解决 Windows 平台和云服务器环境的特有挑战。

部署环境说明：本教程基于阿里云 Windows Server 实例的真实部署经验，演示服务器使用示例IP 192.168.1.100（请替换为您的实际公网IP），支持跨平台客户端（Windows PC 和 Mac）的远程访问。

为什么选择 Gitea？

🚀 轻量级：资源占用少，启动速度快
🔧 易部署：单一可执行文件，无复杂依赖
🌐 功能完整：支持 Issues、Pull Requests、Wiki 等
💾 多数据库支持：SQLite、MySQL、PostgreSQL
🔒 私有可控：本地部署，数据完全掌控

阿里云 Windows 服务器的优势

选择阿里云 Windows Server 作为 Gitea 部署平台具有以下优势：

💻 Windows Server 特色

图形化管理：远程桌面便于维护和故障排查
AD 集成：企业环境下与 Active Directory 无缝集成
开发友好：支持 .NET、PowerShell 等 Windows 技术栈
许可合规：企业级 Windows Server 授权

🔒 网络和安全配置

弹性公网IP：固定外网地址，支持域名绑定
安全组规则：精确控制端口和访问来源
VPC 网络：内网隔离，提升安全性
SSL 证书：支持 HTTPS 加密传输

🔧 环境复杂性

PATH 环境变量：Windows 的 PATH 管理比较复杂，需要正确配置
权限模型：UAC 和文件权限系统与 Unix 系统差异较大
服务管理：Windows 服务注册和管理机制独特
端口冲突：IIS 等系统服务可能占用常用端口

💻 开发工具集成

PowerShell vs CMD：不同命令行环境的兼容性处理
Git 安装：需要单独安装 Git 客户端工具
编码环境：与现代开发工具如 Windsurf、VS Code 的集成

🏢 企业环境适配

防火墙配置：Windows Defender 和企业防火墙设置
网络环境：企业网络代理和访问控制
安全策略：组策略和安全限制的处理

🛠️ 环境准备与预检查

系统要求

阿里云 ECS 实例：Windows Server 2019/2022（推荐）
实例规格：至少 2核4GB（ecs.t5-lc1m2.large 或以上）
网络配置：分配弹性公网IP，配置安全组
存储空间：系统盘 40GB + 数据盘 100GB（推荐）
管理员权限：远程桌面管理员账户

阿里云服务器预配置检查

# 1. 检查服务器基本信息
Get-ComputerInfo | Select-Object WindowsProductName, TotalPhysicalMemory
Get-WmiObject -Class Win32_LogicalDisk | Select-Object DeviceID, Size, FreeSpace# 2. 检查网络配置
ipconfig /all
# 记录内网IP和公网IP信息# 3. 检查安全组配置
# 在阿里云控制台确认以下端口已开放：
# - 3389 (RDP远程桌面)
# - 3000 (Gitea HTTP服务)  
# - 22 (SSH，可选)
# - 443 (HTTPS，可选)# 4. 检查防火墙状态
Get-NetFirewallProfile
netsh advfirewall show allprofiles state

# 1. 检查 Windows 版本和架构
Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion
[Environment]::Is64BitOperatingSystem# 2. 检查管理员权限
([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)# 3. 检查 PowerShell 执行策略
Get-ExecutionPolicy -List# 4. 检查端口可用性
netstat -an | findstr :3000
Test-NetConnection -ComputerName localhost -Port 3000# 5. 检查磁盘空间
Get-WmiObject -Class Win32_LogicalDisk | Select-Object DeviceID, FreeSpace# 6. 检查网络连接
Test-NetConnection -ComputerName google.com -Port 443

Git 环境检查

# 检查 Git 是否已安装
git --version
where git# 如果未安装，需要先安装 Git
# 下载地址：https://git-scm.com/download/win

📦 方法一：直接部署二进制文件（推荐）

1. 下载 Gitea 二进制文件

# 创建工作目录
New-Item -ItemType Directory -Path "C:\gitea" -Force
Set-Location "C:\gitea"# 下载最新版本的 Gitea（Windows 64位）
# 访问 https://dl.gitea.io/gitea/ 获取最新版本
$giteaVersion = "1.21.11"
$downloadUrl = "https://dl.gitea.io/gitea/$giteaVersion/gitea-$giteaVersion-windows-4.0-amd64.exe"
Invoke-WebRequest -Uri $downloadUrl -OutFile "gitea.exe"# 验证下载
.\gitea.exe --version

2. 创建目录结构

# 创建 Gitea 目录结构
New-Item -ItemType Directory -Path "C:\gitea\custom\conf" -Force
New-Item -ItemType Directory -Path "C:\gitea\data\repositories" -Force
New-Item -ItemType Directory -Path "C:\gitea\data\lfs" -Force
New-Item -ItemType Directory -Path "C:\gitea\log" -Force# 查看创建的目录结构
Get-ChildItem -Path "C:\gitea" -Recurse | Format-Table Name, Mode

3. 初始化配置

# 设置环境变量（确保 Git 可用）
$env:PATH += ";C:\Program Files\Git\bin"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Program Files\Git\bin", "Machine")# 首次启动 Gitea（将自动进入安装向导）
Set-Location "C:\gitea"
.\gitea.exe web

4. Web 界面配置

启动后，打开浏览器访问 http://localhost:3000 或 http://服务器公网IP:3000 进行配置：

重要：如果使用阿里云服务器，需要在安全组中开放 3000 端口，并可以通过公网IP访问。

数据库设置

数据库类型：选择 SQLite3（推荐，适合中小规模使用）
数据库文件路径：C:\gitea\data\gitea.db

基本设置

站点名称：自定义，如 “团队代码仓库”
仓库根目录：C:\gitea\data\repositories
Git LFS 根目录：C:\gitea\data\lfs
运行用户：当前 Windows 用户名
服务器域名：your-server-ip（替换为您的服务器公网IP）
SSH 端口：22（如果启用 SSH）
HTTP 端口：3000
应用程序 URL：http://your-server-ip:3000/（替换为您的公网IP）

管理员账户

管理员用户名：admin（建议修改为自定义用户名）
密码：请设置复杂密码，包含大小写字母、数字和特殊字符
确认密码：重复输入密码
管理员邮箱：admin@yourdomain.com（使用您的实际邮箱）

完成配置后点击"立即安装"。

🌐 外部磁盘存储配置（可选）

如果需要将代码仓库存储在其他磁盘，可以进行以下配置：

1. 创建外部存储结构

# 假设使用 D 盘存储
New-Item -ItemType Directory -Path "D:\GitRepositories" -Force
New-Item -ItemType Directory -Path "D:\GitLFS" -Force# 设置合适的权限
icacls "D:\GitRepositories" /grant "$($env:USERNAME):F" /T
icacls "D:\GitLFS" /grant "$($env:USERNAME):F" /T

2. 修改配置文件

编辑 C:\gitea\custom\conf\app.ini：

[repository]
ROOT = D:/GitRepositories[lfs]
PATH = D:/GitLFS

🚀 设置 Windows 服务（开机自启）

使用 NSSM 创建 Windows 服务

# 1. 下载 NSSM (Non-Sucking Service Manager)
# 下载地址：https://nssm.cc/download
# 解压到 C:\nssm# 2. 使用 NSSM 创建服务
C:\nssm\win64\nssm.exe install Gitea# 在弹出的界面中设置：
# Path: C:\gitea\gitea.exe
# Startup directory: C:\gitea
# Arguments: web# 3. 启动服务
Start-Service Gitea# 4. 设置服务开机自启动
Set-Service -Name Gitea -StartupType Automatic

🌐 阿里云网络访问配置

安全组配置

在阿里云 ECS 控制台配置安全组规则：

# 入方向规则配置
端口范围: 3000/3000
授权对象: 0.0.0.0/0 (所有IP，生产环境建议限制特定IP段)
协议类型: TCP
优先级: 1# 可选：HTTPS 支持
端口范围: 443/443  
授权对象: 0.0.0.0/0
协议类型: TCP

内外网访问配置

编辑 C:\gitea\custom\conf\app.ini：

[server]
DOMAIN = your-server-ip  # 替换为您的实际服务器IP
ROOT_URL = http://your-server-ip:3000/
HTTP_ADDR = 0.0.0.0  # 监听所有网络接口
HTTP_PORT = 3000[service]
DISABLE_REGISTRATION = true  # 关闭公开注册（重要安全设置）
ENABLE_CAPTCHA = true

跨平台客户端访问

配置完成后，不同平台的客户端都可以访问：

# Windows 客户端
git clone http://your-server-ip:3000/username/repository.git# Mac 客户端  
git clone http://your-server-ip:3000/username/repository.git# 配置用户信息
git config --global user.name "your-username"
git config --global user.email "your-email@yourdomain.com"

⚠️ 常见问题及解决方案

在 Windows 环境下搭建 Gitea，我们遇到了以下典型问题和解决方案：

问题 1：Git 命令无法识别

现象：

'git' 不是内部或外部命令，也不是可运行的程序或批处理文件

原因分析：

Git 未安装或未正确添加到 PATH 环境变量
PowerShell 会话未刷新环境变量

解决方案：

# 方案 1：手动添加 Git 到 PATH
$gitPath = "C:\Program Files\Git\bin"
if (Test-Path $gitPath) {$currentPath = [Environment]::GetEnvironmentVariable("PATH", "Machine")if ($currentPath -notlike "*$gitPath*") {[Environment]::SetEnvironmentVariable("PATH", "$currentPath;$gitPath", "Machine")}
}# 方案 2：刷新当前会话的环境变量
$env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User")# 方案 3：重新启动 PowerShell 或重启系统

问题 2：阿里云安全组端口访问

现象：

本地可以访问 http://localhost:3000
外网无法访问 http://your-server-ip:3000
浏览器显示：此站点无法访问

原因分析：

阿里云安全组未开放 3000 端口
Windows 防火墙阻止外部访问
Gitea 配置只监听 localhost

解决方案：

# 1. 阿里云控制台配置安全组
# ECS 实例 → 安全组 → 配置规则 → 添加安全组规则
# 端口范围：3000/3000，授权对象：0.0.0.0/0# 2. Windows 防火墙配置
New-NetFirewallRule -DisplayName "Gitea-External" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
New-NetFirewallRule -DisplayName "Gitea-External-Out" -Direction Outbound -Protocol TCP -LocalPort 3000 -Action Allow# 3. 修改 Gitea 配置监听所有接口
# 编辑 C:\gitea\custom\conf\app.ini
[server]
HTTP_ADDR = 0.0.0.0  # 重要：监听所有网络接口
DOMAIN = your-server-ip  # 替换为您的实际IP
ROOT_URL = http://your-server-ip:3000/# 4. 重启 Gitea 服务
Restart-Service Gitea

问题 3：端口 3000 被占用

现象：

listen tcp :3000: bind: Only one usage of each socket address is normally permitted

原因分析：

IIS 或其他 Web 服务占用了 3000 端口
之前的 Gitea 进程未正确关闭

解决方案：

# 查看占用端口的进程
netstat -ano | findstr :3000# 查看进程详情
Get-Process -Id <PID># 终止占用进程
Stop-Process -Id <PID> -Force# 或者使用其他端口
.\gitea.exe web --port 3001

现象：

无法创建目录或写入文件
服务安装失败

原因分析：

当前用户权限不足
UAC（用户账户控制）限制

解决方案：

# 以管理员身份运行 PowerShell
# 检查管理员权限
$isAdmin = ([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
if (-not $isAdmin) {Write-Host "请以管理员身份运行 PowerShell" -ForegroundColor Red
}# 修复目录权限
icacls "C:\gitea" /grant "$($env:USERNAME):F" /T

问题 4：数据库连接失败

现象：

Database connection failed: database locked

原因分析：

SQLite 数据库被锁定
多个 Gitea 实例同时运行
杀毒软件干扰

解决方案：

# 停止所有 Gitea 进程
Get-Process | Where-Object {$_.ProcessName -like "*gitea*"} | Stop-Process -Force# 检查数据库文件权限
Get-Acl "C:\gitea\data\gitea.db"# 临时关闭杀毒软件实时保护
# 或将 Gitea 目录添加到杀毒软件白名单

问题 5：防火墙阻止访问

现象：

本机可以访问，其他机器无法访问
浏览器显示连接超时

解决方案：

# 添加防火墙规则
New-NetFirewallRule -DisplayName "Gitea-Inbound" -Direction Inbound -Protocol TCP -LocalPort 3000 -Action Allow
New-NetFirewallRule -DisplayName "Gitea-Outbound" -Direction Outbound -Protocol TCP -LocalPort 3000 -Action Allow# 查看防火墙状态
Get-NetFirewallProfile# 临时关闭防火墙（不推荐）
# Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

问题 6：仓库创建和连接循环失败

现象：

fatal: repository 'http://localhost:3000/user/repo.git' not found
remote: Not found

原因分析：

仓库需要先在 Gitea Web 界面创建，但 API 创建失败
Git push 到不存在的远程仓库
认证信息配置错误，导致重复尝试失败

解决方案：

# 1. 手动在 Web 界面创建仓库
# 访问 http://localhost:3000，登录后点击 "+" 创建仓库
# 重要：取消勾选 "Initialize Repository"# 2. 验证仓库存在后再连接
git remote add origin http://localhost:3000/username/repository.git
git push -u origin master# 3. 如果认证问题，使用嵌入式认证
git remote set-url origin http://username:password@localhost:3000/username/repository.git

问题 7：环境变量会话丢失

现象：

# 每次新开 PowerShell 都需要重新设置 PATH
git : 无法将"git"项识别为 cmdlet、函数、脚本文件或可运行程序的名称

原因分析：

只设置了当前会话的环境变量
没有持久化到系统级别
重启后环境变量丢失

解决方案：

# 永久解决方案：设置系统级环境变量
$gitPath = "C:\Program Files\Git\bin"
$currentPath = [Environment]::GetEnvironmentVariable("PATH", "Machine")
if ($currentPath -notlike "*$gitPath*") {[Environment]::SetEnvironmentVariable("PATH", "$currentPath;$gitPath", "Machine")
}# 验证设置成功
[Environment]::GetEnvironmentVariable("PATH", "Machine") -split ';' | Select-String "Git"

问题 8：Gitea 服务启动失败

现象：

Error: Git not found, Gitea does not work when Git is not installed.

原因分析：

Gitea 启动时无法找到 Git 可执行文件
服务运行在不同的环境上下文中
系统服务的 PATH 环境与用户会话不同

解决方案：

# 方案 1：在启动 Gitea 前确保环境变量
$env:PATH += ";C:\Program Files\Git\bin"
cd C:\gitea
.\gitea.exe web# 方案 2：修改服务配置（使用 NSSM 时）
# 在 NSSM 服务配置中的 Environment 标签页添加：
# PATH=C:\Program Files\Git\bin;%PATH%# 方案 3：验证 Git 可用性再启动
if (Get-Command git -ErrorAction SilentlyContinue) {.\gitea.exe web
} else {Write-Host "请先解决 Git 环境变量问题" -ForegroundColor Red
}

问题 9：用户注册安全问题

现象：

默认允许任何人注册账户
垃圾账户注册风险

原因分析：

Gitea 默认配置允许公开注册
没有配置管理员审核机制

解决方案：

# 编辑 C:\gitea\custom\conf\app.ini
[service]
DISABLE_REGISTRATION = true
REGISTER_EMAIL_CONFIRM = false
ENABLE_CAPTCHA = true
REQUIRE_SIGNIN_VIEW = false# 重启 Gitea 服务使配置生效
Restart-Service Gitea

问题 10：PowerShell 执行策略限制

现象：

无法加载文件，因为在此系统上禁止运行脚本

原因分析：

Windows 默认的 PowerShell 执行策略过于严格
阻止脚本执行，影响自动化配置

解决方案：

# 检查当前执行策略
Get-ExecutionPolicy -List# 设置当前用户的执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser# 验证设置
Get-ExecutionPolicy -Scope CurrentUser

🛠️ 高级配置与优化

性能优化配置

编辑 C:\gitea\custom\conf\app.ini：

[server]
OFFLINE_MODE = true
DISABLE_ROUTER_LOG = true[database]
MAX_IDLE_CONNS = 30
MAX_OPEN_CONNS = 300
CONN_MAX_LIFETIME = 3600[indexer]
ISSUE_INDEXER_TYPE = bleve
REPO_INDEXER_ENABLED = true[cache]
ENABLED = true
ADAPTER = memory
INTERVAL = 60[session]
PROVIDER = memory

安全配置

[security]
INSTALL_LOCK = true
SECRET_KEY = <生成一个随机的密钥>
DISABLE_GIT_HOOKS = false
DISABLE_WEBHOOKS = false[service]
DISABLE_REGISTRATION = true
REQUIRE_SIGNIN_VIEW = false
ENABLE_CAPTCHA = true

📱 实际部署案例

阿里云服务器配置示例

服务器信息：

实例类型：阿里云 ECS Windows Server 2019
外网IP：your-public-ip（请替换为您的实际公网IP）
内网IP：your-private-ip（请替换为您的实际内网IP）
配置规格：2核4GB
系统盘：40GB SSD

用户账户配置示例：

管理员账户：
- 用户名：admin（建议修改为自定义用户名）
- 密码：请设置复杂密码（至少12位，包含大小写字母、数字、特殊字符）
- 邮箱：admin@yourdomain.com普通用户：
- 用户名：your-username（自定义用户名）
- 密码：请设置复杂密码
- 邮箱：your-email@yourdomain.com

⚠️ 安全提醒：绝不要在生产环境使用示例密码！请务必设置复杂的唯一密码。

创建第一个仓库

# 1. 创建本地项目目录
New-Item -ItemType Directory -Path "C:\Projects\TestGitSync" -Force
Set-Location "C:\Projects\TestGitSync"# 2. 初始化 Git 仓库
git init
git config user.name "your-username"  # 替换为您的用户名
git config user.email "your-email@yourdomain.com"  # 替换为您的邮箱# 3. 创建初始文件
"# TestGit Project" | Out-File -FilePath "README.md" -Encoding UTF8
@"
def hello_world(name="World"):print(f"Hello, {name}!")return f"Welcome to {name}'s repository"if __name__ == "__main__":hello_world("Gitea")
"@ | Out-File -FilePath "hello_world.py" -Encoding UTF8# 4. 提交到本地仓库
git add .
git commit -m "Initial commit: Add README.md and hello_world.py"# 5. 连接远程仓库（先在 Web 界面创建仓库 TestGit）
git remote add origin http://your-server-ip:3000/your-username/TestGit.git
git push -u origin main

跨平台访问验证

Windows 客户端测试：

# 克隆仓库
git clone http://your-server-ip:3000/your-username/TestGit.git
cd TestGit# 修改文件
echo "# Updated from Windows client" >> README.md
git add .
git commit -m "Update from Windows client"
git push origin main

Mac 客户端测试：

# 克隆仓库
git clone http://your-server-ip:3000/your-username/TestGit.git
cd TestGit# 修改文件  
echo "# Updated from Mac client" >> README.md
git add .
git commit -m "Update from Mac client"  
git push origin main

常用管理命令

# 查看 Gitea 服务状态
Get-Service -Name Gitea# 重启 Gitea 服务
Restart-Service -Name Gitea# 查看 Gitea 日志
Get-Content "C:\gitea\log\gitea.log" -Tail 50# 备份 Gitea 数据
Copy-Item "C:\gitea\data" "C:\Backup\gitea-data-$(Get-Date -Format 'yyyyMMdd')" -Recurse# 创建新用户（命令行方式）
Set-Location "C:\gitea"
.\gitea.exe admin user create --admin --username newadmin --password NewPass123 --email newadmin@example.com

🔐 安全建议

定期备份：

# 创建定时备份脚本
$backupScript = @"
`$date = Get-Date -Format "yyyyMMdd_HHmmss"
Copy-Item "C:\gitea\data" "D:\Backup\gitea_`$date" -Recurse
"@
$backupScript | Out-File "C:\Scripts\backup-gitea.ps1"# 创建计划任务
$action = New-ScheduledTaskAction -Execute 'PowerShell.exe' -Argument '-File C:\Scripts\backup-gitea.ps1'
$trigger = New-ScheduledTaskTrigger -Daily -At 2:00AM
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Gitea Backup"

强密码策略：在管理界面设置密码复杂度要求
网络安全：配置适当的防火墙规则，限制访问来源
定期更新：关注 Gitea 官方发布，及时更新到最新版本

🚀 与现代开发工具集成

与 Windsurf IDE 集成

# 1. 在 Windsurf 中配置 Git
# 打开 Windsurf 设置，配置 Git 路径为：C:\Program Files\Git\bin\git.exe# 2. 克隆项目到 Windsurf 工作区
git clone http://localhost:3000/admin/project.git
code . # 使用 Windsurf 打开项目# 3. 配置 SSH 密钥（可选，提高安全性）
ssh-keygen -t rsa -b 4096 -C "your.email@example.com"
# 将公钥添加到 Gitea 用户设置中

团队协作工作流

# 开发者工作流示例
# 1. 克隆仓库
git clone http://localhost:3000/team/project.git
cd project# 2. 创建功能分支
git checkout -b feature/new-feature# 3. 开发和提交
git add .
git commit -m "Add new feature"# 4. 推送分支
git push origin feature/new-feature# 5. 在 Gitea Web 界面创建 Pull Request

📊 监控与维护

系统监控脚本

# 创建 Gitea 健康检查脚本
$healthCheck = @"
# Gitea 健康检查脚本
`$giteaUrl = "http://localhost:3000"
`$logFile = "C:\gitea\log\health-check.log"try {`$response = Invoke-WebRequest -Uri `$giteaUrl -TimeoutSec 10if (`$response.StatusCode -eq 200) {"`$(Get-Date): Gitea is running normally" | Add-Content `$logFile}
} catch {"`$(Get-Date): Gitea health check failed: `$(`$_.Exception.Message)" | Add-Content `$logFile# 可以在这里添加重启服务的逻辑# Restart-Service -Name Gitea
}
"@$healthCheck | Out-File "C:\Scripts\gitea-health-check.ps1"# 创建定时任务（每5分钟检查一次）
$action = New-ScheduledTaskAction -Execute 'PowerShell.exe' -Argument '-File C:\Scripts\gitea-health-check.ps1'
$trigger = New-ScheduledTaskTrigger -Once -At (Get-Date) -RepetitionInterval (New-TimeSpan -Minutes 5)
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "Gitea Health Check"