# Gitea 部署说明

> 部署时间：2026-07-31
>
> 当前阶段：安装已完成，服务正常运行。

## 访问方式

- 正式访问地址：<https://git.zones.sbnews.net/>
- 后端监听：`0.0.0.0:3000`。该端口仍保留用于服务器直连和 Nginx 反向代理，但日常访问应使用 HTTPS 域名。
- 协议：HTTPS（Nginx 终止 TLS，再转发至 Gitea HTTP 3000 端口）
- Git 操作：当前仅启用 HTTP/HTTPS 克隆和推送，未映射 Git SSH 端口，避免与宿主机的 SSH 22 端口冲突。

Nginx 虚拟主机配置位于 `/www/server/panel/vhost/nginx/git.zones.sbnews.net.conf`，反向代理配置位于 `/www/server/panel/vhost/nginx/proxy/git.zones.sbnews.net/`。

## 容器配置

| 项目 | 当前配置 |
| --- | --- |
| 容器名 | `gitea` |
| Gitea 版本 | 1.27.1 |
| 镜像摘要 | `sha256:34e3f6b75f5cbb6aebce588037fc5a53c84213e4d4b00da0a8d73e031a558e52` |
| 重启策略 | `unless-stopped` |
| 端口映射 | `0.0.0.0:3000 -> 3000/tcp` |
| 数据库 | SQLite，数据位于持久化卷内 |
| 数据卷 | `gitea-data`，宿主机位置为 `/var/lib/docker/volumes/gitea-data/_data` |
| 应用根地址 | `https://git.zones.sbnews.net/` |

## 首次初始化

1. 在浏览器打开 <https://git.zones.sbnews.net/>。
2. 使用已创建的管理员账号登录。
3. 创建组织与仓库；初期请使用 HTTPS 克隆地址。

> HTTPS 域名已配置完成。后续更换域名或端口时，需同步更新 Gitea 的 `ROOT_URL` 和 Nginx 反向代理的 `Host` 请求头。

## 反向代理跨域校验修复

2026-07-31 曾出现 `cross-origin request detected` 与 `Frontend is not initialized` 提示。根因是 Nginx 反代把请求头设置为 `Host: localhost`，而浏览器请求的 `Origin` 是 `https://git.zones.sbnews.net`，导致 Gitea 的 CSRF 校验拒绝表单提交。

已将反代请求头改为：

~~~
proxy_set_header Host git.zones.sbnews.net;
proxy_set_header X-Forwarded-Host git.zones.sbnews.net;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Port 443;
~~~

并将 Gitea 的 `DOMAIN`、`ROOT_URL` 更新为 `git.zones.sbnews.net` 和 `https://git.zones.sbnews.net/`。修改后 Nginx 配置检查、Gitea 健康检查、HTTPS 页面与浏览器静态资源加载均已验证通过。

## 常用运维命令

以下命令均在服务器上执行：

~~~
ssh sbnews
sudo docker ps --filter name=gitea
sudo docker logs --tail 200 gitea
sudo docker restart gitea
sudo docker stop gitea
sudo docker start gitea
sudo docker volume inspect gitea-data
~~~

## 注意事项

- Gitea 数据存放在 Docker 卷中。备份或迁移前先确认容器已停止，或使用 Gitea 官方备份方式，避免只备份容器层。
- 当前镜像已固定到上述摘要，不会随宿主机重启自动升级。升级前应先备份数据，并在测试环境验证目标版本。
- 调整端口、域名、HTTPS 或 Git SSH 后，应同步更新本文档、[服务器运行环境](./服务器运行环境.md) 和 [文档索引](../文档索引.md)。