Gitea Docker 部署教程

本教程将指导您在云服务器上部署 Gitea，并仅绑定到指定的内网 IP（10.10.233.1） ，不向公网暴露服务。数据持久化目录设为 /opt/gitea，Web 端口 3000，SSH 外部端口 222（内部 22）。

---

1. 环境准备

1.1 安装 Docker（若未安装）

curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker

1.2 创建数据目录并设置权限

Gitea 容器内运行用户 UID 为 1000，需确保宿主机目录可写：

sudo mkdir -p /opt/gitea
sudo chown -R 1000:1000 /opt/gitea
sudo chmod -R 755 /opt/gitea

若父目录 /opt 权限过严，请执行 sudo chmod 755 /opt（通常默认即可）。

---

2. 拉取镜像

推荐使用官方镜像源（避免 Docker Hub 限流）：

docker pull docker.1panel.live/gitea/gitea:1.27.0

或使用 Gitea 官方自建仓库：

docker pull docker.gitea.com/gitea:1.27.0

---

3. 启动容器（绑定内网 IP）

使用 docker run 命令，将宿主机上的内网 IP 10.10.233.1 与容器端口进行映射，这样只有能访问该 IP 的客户端才能连接。

docker run -d \
  --name gitea \
  --restart always \
  -p 10.10.233.1:3000:3000 \
  -p 10.10.233.1:222:22 \
  -v /opt/gitea/data:/data/gitea \
  -v /opt/gitea/conf:/data/gitea/conf \
  docker.1panel.live/gitea/gitea:1.27.0

参数说明：

参数	含义
-d	后台运行
--name=gitea	容器名称
--restart=always	自动重启
-p 10.10.233.1:3000:3000	仅在内网 IP 10.10.233.1 上监听 Web 端口 3000
-p 10.10.233.1:222:22	仅在内网 IP 10.10.233.1 上监听 SSH 端口 222，映射至容器内 22
-v /opt/gitea:/data	持久化数据至 /opt/gitea

注意 ：宿主机必须已配置 10.10.233.1 这个 IP（例如通过 WireGuard 或虚拟网卡），否则容器启动会因无法绑定而失败。确保该 IP 存在且可用。

---

4. 检查运行状态

docker ps | grep gitea

状态应为 Up。若反复重启，请查看日志：

docker logs gitea --tail 50

---

5. 初始化配置（Web 安装）

5.1 访问安装页面

在能够访问 10.10.233.1 的客户端（如 VPN 内的机器）浏览器中打开：

http://10.10.233.1:3000

首次访问会自动跳转至安装页面。

5.2 关键配置项填写

配置项	填写内容	说明
仓库根目录	/data/git/repositories	默认，无需修改
LFS根目录	/data/git/lfs	留空禁用 LFS
以用户名运行	git（自动检测）	无需改动
服务器域名	10.10.233.1	填写内网 IP
SSH 服务端口	22	容器内部 SSH 端口（外部映射为 222）
HTTP 服务端口	3000	保持不变
基础 URL	http://10.10.233.1:3000/	自动生成，检查是否正确
日志路径	/data/gitea/log	默认

重点 ：SSH 服务端口 填 22，否则容器内 SSH 会监听错误端口导致失败。其余选项（数据库、管理员账号）按需配置，建议先选 SQLite3 快速开始。

5.3 点击"安装"完成初始化

安装完成后会跳转至登录页面。

---

6. 修正 SSH 外部端口显示（必须）

安装后，Web 界面上的克隆地址默认显示端口 22（因为内部监听 22），但外部实际使用端口 222。需修改配置文件，让 Gitea 对外公布 222。

6.1 编辑配置文件

sudo vi /opt/gitea/conf/app.ini

6.2 添加或修改以下参数

在 [server] 段落下：

[server]
SSH_PORT = 222
SSH_LISTEN_PORT = 22

• SSH_PORT：对外显示的端口（克隆 URL 中显示）
• SSH_LISTEN_PORT：容器内部实际监听的端口（保持 22）

若文件中已有 SSH_PORT，直接修改数值；若没有则新增。

6.3 重启容器使配置生效

docker restart gitea

等待几秒后刷新 Web 页面，仓库克隆地址应显示 ssh://git@10.10.233.1:222/...。

---

7. 验证服务

7.1 检查容器日志

docker logs gitea --tail 50

应无 permission denied 或 address already in use 错误。

7.2 测试 SSH 连接（从内网客户端）

ssh -p 222 git@10.10.233.1

返回 Hi there, ... 或 Permission denied (publickey) 表示服务正常（公钥认证失败是预期行为）。

7.3 测试 HTTP 克隆

在 Gitea 中创建测试仓库，通过 HTTP 或 SSH 克隆，确认功能正常。

---

8. 使用 Docker Compose（备选）

创建 docker-compose.yml：

version: "3"

services:
  server:
    image: docker.1panel.live/gitea/gitea:1.27.0
    container_name: gitea
    restart: always
    ports:
      - "10.10.233.1:3000:3000"
      - "10.10.233.1:222:22"
    volumes:
      - /opt/gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro

启动：

docker-compose up -d

后续操作（安装、修改 app.ini）与 docker run 方式相同。

---

9. 常见问题排查

9.1 容器无法启动（Restarting）

• 权限问题 ：日志显示 permission denied → 执行 sudo chown -R 1000:1000 /opt/gitea 并重启。
• 端口绑定失败 ：确认 10.10.233.1 是否存在且未被占用（netstat -tlnp | grep 3000）。
• SELinux （CentOS/RHEL）：临时关闭 sudo setenforce 0 测试，若正常则设置目录上下文：

sudo chcon -Rt svirt_sandbox_file_t /opt/gitea
sudo setenforce 1

9.2 克隆地址端口不对

检查 app.ini 中 SSH_PORT 是否为 222，并已重启容器。

9.3 无法通过 SSH 克隆

• 确认客户端能 ping 通 10.10.233.1。
• 检查宿主机防火墙是否允许 222 端口的入站连接（仅限内网）：

sudo firewall-cmd --add-port=222/tcp --permanent  # firewalld
sudo ufw allow from 10.10.0.0/24 to any port 222 proto tcp  # ufw，限制来源

• 确保容器内 SSH 服务运行：docker exec gitea ps aux | grep sshd。

9.4 忘记管理员密码

docker exec -it gitea ./gitea admin user create --username admin --password <新密码> --email admin@example.com

---

10. 升级与备份

10.1 升级 Gitea

docker stop gitea
docker rm gitea
docker pull docker.1panel.live/gitea/gitea:1.28.0   # 新版本
# 重新运行相同的启动命令（数据保留）
docker run -d --name=gitea --restart=always \
  -p 10.10.233.1:3000:3000 -p 10.10.233.1:222:22 \
  -v /opt/gitea:/data \
  docker.1panel.live/gitea/gitea:1.28.0

10.2 数据备份

sudo tar -czf gitea-backup-$(date +%Y%m%d).tar.gz /opt/gitea

恢复时解压至 /opt/gitea 并修正权限。

---

11. 安全建议

• 防火墙限制 ：仅允许内网 IP 范围（如 10.10.0.0/16）访问 3000 和 222 端口。
• 云服务商安全组 ：删除允许公网访问 3000 的规则，仅保留必要的 WireGuard 端口。
• 启用 HTTPS：若需加密传输，可在前端配置 Nginx 反向代理并绑定到内网 IP。
• 定期更新：及时更新 Gitea 镜像以修复漏洞。

---

12. 结语

至此，Gitea 已部署并仅监听内网 IP 10.10.233.1，数据存放在 /opt/gitea。通过 VPN 或内网环境即可安全访问，公网无法直接触及。

如有其他问题，请查看容器日志 docker logs gitea 获取详细错误信息。