# 团队 Git 远端仓库搭建方案

本文档用于在香港地区 Debian 服务器上部署团队共享 Git 服务，并为后续绑定域名和 HTTPS 做准备。

推荐技术栈：

- Gitea：Git 仓库、用户、组织、权限、Issue 和合并请求
- PostgreSQL：Gitea 数据库
- Caddy：反向代理和自动 HTTPS
- Docker Compose：部署和升级

## 一、推荐架构

```text
开发者浏览器 / Git 客户端
        │
        ├── https://git.example.com
        │        │
        │       Caddy：HTTPS、反向代理
        │        │
        │       Gitea：Web 管理、仓库服务
        │        │
        │       PostgreSQL：用户、权限、仓库元数据
        │
        └── SSH git@git.example.com:team/project.git
```

建议服务器至少具备：

- 2 核 CPU、4 GB 内存、40 GB SSD
- 独立公网 IPv4
- 服务器安全组开放 TCP 22、80、443、2222

## 二、检查系统并安装 Docker

先确认系统版本和架构：

```bash
cat /etc/os-release
uname -m
```

服务器应使用 Debian 11/12/13 的 amd64 架构。以下以 Debian 12（Bookworm）为例；如果系统版本不同，请替换仓库中的代号。

```bash
apt update
apt install -y ca-certificates curl gnupg

install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

cat >/etc/apt/sources.list.d/docker.sources <<'EOF'
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: bookworm
Components: stable
Architectures: amd64
Signed-By: /etc/apt/keyrings/docker.asc
EOF

apt update
apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

systemctl enable --now docker
docker run hello-world
```

## 三、创建部署目录

```bash
mkdir -p /opt/gitea/{gitea,postgres,caddy}
cd /opt/gitea
```

创建 `/opt/gitea/docker-compose.yml`：

```yaml
services:
  db:
    image: postgres:16
    container_name: gitea-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: gitea
      POSTGRES_PASSWORD: 请替换为高强度数据库密码
      POSTGRES_DB: gitea
    volumes:
      - ./postgres:/var/lib/postgresql/data
    networks:
      - gitea

  gitea:
    image: docker.gitea.com/gitea:latest
    container_name: gitea
    restart: unless-stopped
    depends_on:
      - db
    environment:
      USER_UID: 1000
      USER_GID: 1000
      GITEA__database__DB_TYPE: postgres
      GITEA__database__HOST: db:5432
      GITEA__database__NAME: gitea
      GITEA__database__USER: gitea
      GITEA__database__PASSWD: 请替换为高强度数据库密码
      GITEA__server__DOMAIN: git.example.com
      GITEA__server__ROOT_URL: https://git.example.com/
      GITEA__server__SSH_DOMAIN: git.example.com
      GITEA__server__SSH_PORT: 2222
    ports:
      - "3000:3000"
      - "2222:22"
    volumes:
      - ./gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    networks:
      - gitea

  caddy:
    image: caddy:2
    container_name: gitea-caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./caddy/Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy/data:/data
      - ./caddy/config:/config
    networks:
      - gitea

networks:
  gitea:
```

正式部署时应将数据库密码替换为随机高强度密码，并建议固定经过验证的 Gitea 镜像版本，而不是长期使用 `latest`。

## 四、配置域名和 HTTPS

创建 `/opt/gitea/caddy/Caddyfile`：

```caddyfile
git.example.com {
    reverse_proxy gitea:3000
}
```

将 `git.example.com` 替换为实际域名，并在 DNS 服务商增加：

```text
类型：A
主机记录：git
记录值：服务器公网 IPv4
```

确保域名已经解析到服务器，并开放 TCP 80 和 443。Caddy 会自动申请、续期 HTTPS 证书，并将 HTTP 跳转到 HTTPS。

启动服务：

```bash
cd /opt/gitea
docker compose up -d
docker compose ps
```

## 五、初始化 Gitea

访问：

```text
https://git.example.com
```

安装页面填写：

```text
数据库类型：PostgreSQL
数据库主机：db:5432
数据库名称：gitea
数据库用户：gitea
数据库密码：docker-compose.yml 中设置的密码
站点 URL：https://git.example.com/
SSH 服务器域名：git.example.com
SSH 端口：2222
```

创建第一个管理员账号后，建议建立团队组织，例如 `AItrackwalker`，再按成员职责授予权限：

- Owner：项目负责人
- Admin：维护者
- Write：开发者
- Read：只读成员

成员可以使用以下地址克隆仓库：

```bash
git clone ssh://git@git.example.com:2222/AItrackwalker/project.git
```

成员使用自己的 SSH 密钥，不要共享 Git 账号：

```bash
ssh-keygen -t ed25519 -C "成员邮箱"
cat ~/.ssh/id_ed25519.pub
```

将公钥添加到 Gitea 的“个人设置 → SSH/GPG 密钥”。

## 六、备份

Git 仓库、用户、权限、Issue 等数据分布在 Gitea 数据目录和 PostgreSQL 数据库中，两者都必须备份。

```bash
mkdir -p /opt/backup/gitea

docker exec gitea-db pg_dump -U gitea gitea \
  > /opt/backup/gitea/gitea-$(date +%F).sql

tar -czf /opt/backup/gitea/data-$(date +%F).tar.gz \
  /opt/gitea/gitea
```

建议每天备份，保留 7～30 天，并将至少一份备份复制到另一台服务器或对象存储。定期进行恢复测试，不要只保留服务器本地备份。

## 七、安全建议

- 管理 SSH 使用密钥登录，禁止 root 密码登录
- Gitea 关闭公开注册，采用邀请制
- 管理员账号启用 2FA
- 限制普通成员创建组织和管理员账号
- 不要暴露 PostgreSQL 的 5432 端口
- Docker 镜像升级前先做完整备份
- 使用 `.gitignore` 防止提交 `.env`、密码和密钥
- 对敏感代码考虑使用 VPN 或 IP 白名单
- 开启 Debian 自动安全更新：

```bash
apt install -y unattended-upgrades
dpkg-reconfigure unattended-upgrades
```

## 八、后续扩展

初期使用 Gitea 即可。后续如需 CI/CD，可添加 Gitea Actions Runner；如需更复杂的代码扫描、容器镜像仓库和企业级审计，再评估 GitLab。

参考文档：

- [Docker Engine on Debian](https://docs.docker.com/engine/install/debian/)
- [Gitea Installation](https://docs.gitea.com/category/installation)
- [Gitea HTTPS Setup](https://docs.gitea.com/usage/https-setup)
- [Caddy Automatic HTTPS](https://caddyserver.com/docs/automatic-https)
