                    ┌──────────────────────────────────────────┐
                    │              云服务器                      │
  用户 ───HTTPS───→ │  Nginx:443 ──→ Gitea:3000                │
  用户 ───SSH────→  │  端口:2222  ──→ Gitea SSH                 │
                    │                  ↓                        │
                    │              MySQL:3306                    │
                    │                                           │
                    │  /opt/gitea/          部署文件 (compose等) │
                    │  /var/lib/gitea/      仓库+LFS+附件+密钥   │
                    │  /var/lib/mysql/gitea/ MySQL 数据           │
                    │  /var/backups/gitea/  备份文件              │
                    └──────────────────────────────────────────┘

组件	版本	说明
Gitea	1.25	Git 托管服务（含内置 SSH 服务器）
MySQL	8.0	数据库（utf8mb4）
Nginx	系统包	HTTPS 反向代理
Certbot	系统包	Let's Encrypt 自动 SSL 证书
Docker	最新	容器运行时

已启用功能

HTTPS：Nginx + Let's Encrypt 免费 SSL，自动续期
Git LFS：大文件存储，支持最大 4GB 单文件上传
SSH 密钥：内置 SSH 服务器，支持 Ed25519/RSA 等密钥
GPG 签名：提交签名验证，显示 "Verified" 徽标

一、前置条件

项目	要求
服务器	2核 2GB+ 内存，50GB+ SSD
系统	Ubuntu 20.04+ / Debian 11+
域名	已解析 A 记录到服务器 IP
端口	80、443、2222 可从外网访问

如果使用云厂商（阿里云/腾讯云/AWS），需要在安全组中放行上述端口。

二、一键部署（全新服务器）

步骤 1：上传部署文件

# 在本地执行，将文件上传到服务器
scp -r gitea/ root@服务器IP:/opt/gitea

步骤 2：首次运行，生成配置

ssh root@服务器IP
cd /opt/gitea
chmod +x deploy.sh backup.sh

# 首次运行 → 自动安装系统依赖 + Docker + Nginx
# 然后生成 .env 配置文件（密码已随机生成）并退出
bash deploy.sh

步骤 3：修改域名配置

vi .env

必须修改的字段：

GITEA_DOMAIN=git.yourdomain.com    # ← 你的实际域名
CERTBOT_EMAIL=you@yourdomain.com   # ← 你的邮箱（证书通知用）

可选修改：

SSH_PORT=2222                  # Git SSH 端口
GPG_SIGNING_NAME=Gitea         # GPG 签名显示名称
GPG_SIGNING_EMAIL=git@xxx.com  # GPG 签名邮箱
DISABLE_REGISTRATION=false     # 部署完成后改为 true
REQUIRE_SIGNIN=false           # 私有部署改为 true

步骤 4：执行部署

bash deploy.sh

脚本会自动完成以下 8 个步骤：

步骤	操作
1/8	系统更新，安装基础工具（curl, git, openssl 等）
2/8	安装 Docker + Docker Compose V2
3/8	安装 Nginx
4/8	验证 .env 配置
5/8	创建数据目录
6/8	配置防火墙（UFW/Firewalld）
7/8	申请 SSL 证书 + 配置 Nginx HTTPS 反向代理
8/8	拉取镜像，启动 Gitea + MySQL 容器

步骤 5：初始化 Gitea

浏览器打开 https://git.yourdomain.com
进入安装向导（数据库已自动配置好）
创建管理员账户（务必设置强密码）
点击 "安装 Gitea"

步骤 6：安装后加固

cd /opt/gitea

# 关闭公开注册
sed -i 's/DISABLE_REGISTRATION=false/DISABLE_REGISTRATION=true/' .env
# 要求登录才能浏览
sed -i 's/REQUIRE_SIGNIN=false/REQUIRE_SIGNIN=true/' .env

# 重启生效
docker compose up -d

三、功能使用指南

SSH 密钥认证

# 1. 本地生成密钥（如果还没有）
ssh-keygen -t ed25519 -C "your@email.com"

# 2. 复制公钥
cat ~/.ssh/id_ed25519.pub

# 3. 在 Gitea 中添加
#    → 头像 → 设置 → SSH/GPG 密钥 → 添加密钥 → 粘贴公钥

# 4. 测试连接
ssh -T git@git.yourdomain.com -p 2222

# 5. 克隆仓库
git clone ssh://git@git.yourdomain.com:2222/用户名/仓库.git

GPG 签名提交

# 1. 生成 GPG 密钥
gpg --full-generate-key
# 选择 RSA and RSA → 4096 → 填写名字和邮箱

# 2. 查看密钥 ID
gpg --list-secret-keys --keyid-format=long
# 输出中 sec 行的 XXXXXXXXXXXXXXXX 就是密钥 ID

# 3. 导出公钥
gpg --armor --export XXXXXXXXXXXXXXXX

# 4. 在 Gitea 中添加
#    → 头像 → 设置 → SSH/GPG 密钥 → 添加 GPG 密钥 → 粘贴公钥

# 5. 配置 Git 使用 GPG 签名
git config --global user.signingkey XXXXXXXXXXXXXXXX
git config --global commit.gpgsign true

# 6. 签名提交（之后所有 commit 自动签名）
git commit -S -m "signed commit"

Git LFS 大文件

# 1. 安装 Git LFS（本地）
git lfs install

# 2. 跟踪大文件类型
git lfs track "*.psd"
git lfs track "*.zip"
git lfs track "*.bin"

# 3. 提交
git add .gitattributes
git add large-file.psd
git commit -m "add large file via LFS"
git push

四、日常运维

查看状态与日志

cd /opt/gitea

# 容器状态
docker compose ps

# 实时日志
docker compose logs -f          # 所有
docker compose logs -f server   # 仅 Gitea
docker compose logs -f db       # 仅 MySQL

重启 / 停止 / 启动

docker compose restart        # 重启所有
docker compose restart server # 仅重启 Gitea
docker compose down           # 停止并移除容器
docker compose up -d          # 启动

升级 Gitea

cd /opt/gitea

# 1. 先备份
bash backup.sh

# 2. 拉取新镜像
docker compose pull

# 3. 重启
docker compose up -d

# 4. 检查日志
docker compose logs -f server

定时自动备份

# 每天凌晨 3 点自动备份
crontab -e
# 添加：
0 3 * * * /opt/gitea/backup.sh >> /var/backups/gitea/cron.log 2>&1

备份内容：

db_日期.sql.gz — MySQL 完整转储
gitea_data_日期.tar.gz — 仓库 + LFS + 附件 + 头像 (/var/lib/gitea/)
config_日期.tar.gz — .env + docker-compose.yml + nginx 配置

恢复备份

cd /opt/gitea

# 1. 停止服务
docker compose down

# 2. 恢复 Gitea 数据目录
tar xzf /var/backups/gitea/gitea_data_20260406_030000.tar.gz -C /var/lib/

# 3. 恢复配置
tar xzf /var/backups/gitea/config_20260406_030000.tar.gz -C /opt/gitea/

# 4. 启动 MySQL
docker compose up -d db
sleep 10

# 5. 恢复数据库
gunzip < /var/backups/gitea/db_20260406_030000.sql.gz | \
    docker compose exec -T db mysql -u root -p"${DB_ROOT_PASSWORD}"

# 6. 启动全部
docker compose up -d

五、安全加固清单

域名已启用 HTTPS（deploy.sh 自动完成）
SSL 证书自动续期（deploy.sh 自动配置 cron）
关闭公开注册（DISABLE_REGISTRATION=true）
启用登录才能浏览（REQUIRE_SIGNIN=true）
配置防火墙仅开放 80/443/2222（deploy.sh 自动完成）
云安全组已放行对应端口
服务器 SSH 改为密钥登录，禁用密码
定时备份已配置
MySQL root 密码为随机强密码（deploy.sh 自动生成）
Gitea HTTP 端口仅监听 127.0.0.1（不对外暴露）

六、常见问题

Q: SSL 证书申请失败？

确认域名 A 记录已解析到服务器 IP（用 dig git.yourdomain.com 验证）
确认 80 端口可从外网访问（云安全组 + 防火墙）
等 DNS 生效后重新运行 bash deploy.sh

Q: 忘记管理员密码？

docker compose exec server gitea admin user change-password -u 管理员用户名 -p 新密码

Q: Git LFS push 失败 / 超时？

Nginx 已配置 client_max_body_size 4G（LFS 路径单独配置）
如仍超时，检查服务器带宽和磁盘空间

Q: GPG 签名的提交不显示 "Verified"？

确认 GPG 公钥已添加到 Gitea 用户设置
确认 Git 提交邮箱与 GPG 密钥邮箱一致

Q: 如何迁移到新服务器？

旧服务器执行 bash backup.sh
复制部署目录 /opt/gitea/、数据 /var/lib/gitea/、备份 /var/backups/gitea/ 到新服务器
新服务器执行 bash deploy.sh
修改域名 DNS 指向新服务器 IP
重新申请 SSL 证书：certbot certonly --webroot -w /var/www/certbot -d 域名

服务器目录结构

/opt/gitea/                         # 部署目录（INSTALL_DIR）
├── docker-compose.yml              # Gitea + MySQL 容器编排
├── .env.example                    # 环境变量模板
├── .env                            # 运行时配置（自动生成）
├── deploy.sh                       # 全新服务器一键部署脚本
├── backup.sh                       # MySQL + 数据备份脚本
├── .gitignore
├── README.md
└── nginx/
    └── gitea.conf                  # Nginx HTTPS 反向代理模板

/var/lib/gitea/                     # Gitea 应用数据（GITEA_DATA_DIR）
├── gitea/
│   ├── conf/app.ini                # Gitea 运行配置（首次安装后生成）
│   ├── repositories/               # Git 仓库文件
│   ├── lfs/                        # Git LFS 对象存储
│   ├── attachments/                # Issue / Release 附件
│   ├── avatars/                    # 用户头像
│   └── ...                         # 其他运行时数据
├── git/                            # Git 用户 home
└── ssh/                            # SSH 密钥

/var/lib/mysql/gitea/               # MySQL 数据文件（MYSQL_DATA_DIR）

/var/backups/gitea/                 # 备份文件（BACKUP_DIR）
├── db_日期.sql.gz                  # MySQL 转储
├── gitea_data_日期.tar.gz          # Gitea 数据快照
├── config_日期.tar.gz              # 配置备份
└── cron.log                        # 定时备份日志

/etc/nginx/sites-available/gitea    # Nginx HTTPS 配置（由 deploy.sh 生成）
/etc/letsencrypt/live/域名/         # SSL 证书（由 Certbot 管理）

README.md Unescape Escape

Gitea 云服务器部署指南

架构概览

已启用功能

一、前置条件

二、一键部署（全新服务器）

步骤 1：上传部署文件

步骤 2：首次运行，生成配置

步骤 3：修改域名配置

步骤 4：执行部署

步骤 5：初始化 Gitea

步骤 6：安装后加固

三、功能使用指南

SSH 密钥认证

GPG 签名提交

Git LFS 大文件

四、日常运维

查看状态与日志

重启 / 停止 / 启动

升级 Gitea

定时自动备份

恢复备份

五、安全加固清单

六、常见问题

服务器目录结构

README.md