目录

1. 方案对比：选二进制还是 Docker？
2. Linux 二进制安装（以 Ubuntu 22.04 为例）
3. Linux Docker-Compose 一键安装
4. Windows 11 图形化安装（含注册系统服务）
5. 首次初始化 & 创建第一个仓库
6. 常用维护：备份、升级、HTTPS 反向代理
7. 常见问题 FAQ

1.方案对比：选二进制还是 Docker？

• 纯新手 / 想最快体验 → Docker（见第 3 节）
• 老运维 / 追求极致轻量 → 二进制（见第 2 节）

2.Linux 二进制安装（Ubuntu 22.04）

2.1 创建专用用户

sudo adduser --system --group --disabled-password --home /var/lib/gitea gitea

2.2 下载二进制
wget -O /usr/local/bin/gitea https://dl.gitea.com/gitea/1.22.0/gitea-1.22.0-linux-amd64
sudo chmod +x /usr/local/bin/gitea
sudo chown gitea:gitea /usr/local/bin/gitea

2.3 创建必要目录
sudo mkdir -p /etc/gitea /var/lib/gitea/{custom,data,log}
sudo chown -R gitea:gitea /etc/gitea /var/lib/gitea

2.4 Systemd 服务（/etc/systemd/system/gitea.service）

[Unit]
Description=Gitea
After=network.target

[Service]
Type=simple
User=gitea
WorkingDirectory=/var/lib/gitea
ExecStart=/usr/local/bin/gitea web --config /etc/gitea/app.ini
Restart=always

[Install]
WantedBy=multi-user.target

生效并自启
sudo systemctl daemon-reload
sudo systemctl enable --now gitea

2.5 放通防火墙
sudo ufw allow 3000/tcp

浏览器访问 http://服务器IP:3000 进入初始化页面（见第 5 节）。

3.Linux Docker-Compose 一键安装

3.1 安装 Docker & Compose（略）

3.2 创建工作目录
sudo mkdir -p /opt/gitea && cd /opt/gitea

3.3 编写 docker-compose.yml

services:
gitea:
image: gitea/gitea:1.22.0
container_name: gitea
environment:
- USER_UID=1000
- USER_GID=1000
- DB_TYPE=sqlite3   # 想换 MySQL 见注释
volumes:
- ./data:/data
ports:
- "3000:3000"
- "222:22"         # 内置 SSH
restart: unless-stopped

3.4 启动
docker compose up -d

3.5 设置反向代理（可选，见第 6 节）

4.Windows 11 图形化安装

4.1 前置条件

• 安装 Git for Windows（官方下载即可）
• 下载 gitea-1.22.0-windows-4.0-amd64.exe 并重命名为 gitea.exe

4.2 创建目录
C:\gitea\gitea.exe
C:\gitea\data\gitea.db（SQLite 会自动生成）

4.3 首次运行
在 cmd 中：

cd C:\gitea
gitea.exe web

浏览器打开 http://localhost:3000 完成初始化（见第 5 节）。
关闭窗口即停服务，适合临时测试。

4.4 注册为 Windows 服务（长期运行）
以管理员 PowerShell：

sc.exe create gitea start= auto binPath= "\"C:\gitea\gitea.exe\" web --config \"C:\gitea\custom\conf\app.ini\""
sc.exe start gitea

4.5 防火墙放行
“允许应用”里把 gitea.exe 加入，端口 3000 & 22。

5.首次初始化 & 创建第一个仓库

无论哪种安装，首次访问都会进入“Install page”，按下图填写：

图 1 初始化页面示意
（图略：依次填写数据库类型 / 管理员账号 / 仓库根路径 / 基础 URL）

关键点

• 数据库：单机测试选 SQLite；生产建议 MySQL 或 PostgreSQL。
• 基础 URL：如果后面要挂域名，直接写成 https://git.example.com，省得改配置。
• 管理员：初始化页面只能建一个 admin，后续可在后台加人。

初始化完自动跳到登录页，用刚创建的 admin 账号进入：

图 2 登录后首页
点击右上角 “+” → “New Repository”：

图 3 新建仓库页面
填写 Name = hello-gitea，勾选 “Initialize Repository” → 创建。

图 4 仓库首页已生成
本地推送测试

git clone http://服务器IP:3000/admin/hello-gitea.git
cd hello-gitea
echo "# hello" >> README.md
git add . && git commit -m "first"
git push origin main

刷新页面即可看到提交记录，至此私有 Git 服务器已可正常使用。

6.常用维护

6.1 备份
二进制：

停服务

sudo systemctl stop gitea

打包三件套

sudo tar -zcvf gitea-backup-$(date +%F).tar.gz /var/lib/gitea /etc/gitea

起服务

sudo systemctl start gitea

Docker：
docker exec -it gitea sh -c 'gitea dump -c /data/gitea/conf/app.ini -f /data/dump.zip'
结果会生成在 /opt/gitea/data/dump.zip，直接拷走即可。

6.2 升级
二进制：下载新版 → 替换 /usr/local/bin/gitea → 重启服务。
Docker：docker compose pull && docker compose up -d。

6.3 HTTPS 反向代理（Nginx 示例）

server {
    listen 443 ssl http2;
    server_name git.example.com;
    ssl_certificate /etc/letsencrypt/live/git.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/git.example.com/privkey.pem;
    location / {  
        proxy_pass http://127.0.0.1:3000;  
        proxy_set_header Host $host;  
        proxy_set_header X-Real-IP $remote_addr;  
    }
}

配置完后把 [server] 里的 ROOT_URL 改为 https://git.example.com 并重启 Gitea。

7.常见问题 FAQ

Q1 端口 3000 被占用？
A：app.ini 里改 HTTP_PORT = 3030，或 docker-compose 里改端口映射。

Q2 无法推送大文件？
A：开启 LFS，网页 → Site Admin → Configuration → ENABLE LFS = true；客户端安装 git-lfs。

Q3 忘记 admin 密码？
A：

docker exec -it gitea gitea admin user change-password -u admin -p NewPass123

或二进制：

sudo -u gitea gitea admin user change-password -u admin -p NewPass123

Q4 想多人协作，如何注册新用户？A：

• 关闭注册：app.ini 设 DISABLE_REGISTRATION = true，由 admin 后台手动添加用户。
• 开放注册：保持默认，用户在登录页自行注册。