---
name: gitea-deploy
description: Deploy Gitea (self-hosted Git service) with PostgreSQL using Docker Compose. Use when user wants to set up Gitea for Git repository hosting.
tools: Read, Glob, Grep, Bash
---

# Gitea Docker 部署

使用 Docker Compose 部署 Gitea 自託管 Git 服務（含 PostgreSQL 資料庫）。

## 前置需求

- **目標**: 已安裝 Docker 的伺服器
- **存取**: SSH root 權限
- **目錄**: 服務部署於 `/opt/docker/gitea/`

## 部署步驟

### Step 1: 建立目錄與配置

```bash
ssh root@<SERVER_IP> bash -c '
mkdir -p /opt/docker/gitea
cat > /opt/docker/gitea/docker-compose.yml << "EOF"
networks:
  gitea:
    external: false

volumes:
  gitea:
    driver: local
  postgres:
    driver: local

services:
  server:
    image: docker.gitea.com/gitea:1.22.3
    container_name: gitea
    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
    restart: always
    networks:
      - gitea
    volumes:
      - gitea:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
    depends_on:
      - db

  db:
    image: docker.io/library/postgres:14
    container_name: gitea-db
    restart: always
    environment:
      - POSTGRES_USER=gitea
      - POSTGRES_PASSWORD=gitea
      - POSTGRES_DB=gitea
    networks:
      - gitea
    volumes:
      - postgres:/var/lib/postgresql/data
EOF
'
```

### Step 2: 啟動服務

```bash
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose up -d"
```

### Step 3: 驗證部署

```bash
ssh root@<SERVER_IP> "docker ps | grep gitea"
```

**預期輸出**：
```
gitea      Up    0.0.0.0:3000->3000/tcp, 0.0.0.0:222->22/tcp
gitea-db   Up    5432/tcp
```

## 存取資訊

- **Web 介面**: `http://<SERVER_IP>:3000`
- **SSH**: `ssh git@<SERVER_IP>:222`

## 初始設定

首次訪問 `http://<SERVER_IP>:3000` 時，需填寫：

**資料庫設定**：
- **資料庫類型**: PostgreSQL
- **資料庫主機**: `db:5432`
- **資料庫使用者**: `gitea`
- **資料庫密碼**: `gitea`
- **資料庫名稱**: `gitea`

**其他設定可保持預設值。**

## 常用指令

```bash
# 查看狀態
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose ps"

# 查看日誌
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose logs"

# 停止服務
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose down"

# 重啟服務
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose restart"

# 更新映像
ssh root@<SERVER_IP> "cd /opt/docker/gitea && docker compose pull && docker compose up -d"

# 進入容器
ssh root@<SERVER_IP> "docker exec -it gitea bash"
```

## 連接埠說明

| 連接埠 | 用途 |
|--------|------|
| 3000 | Web 介面 |
| 222 | SSH Git 操作 |

## 備份

```bash
# 備份資料庫
ssh root@<SERVER_IP> "docker exec gitea-db pg_dump -U gitea gitea > gitea_backup.sql"

# 備份資料卷
ssh root@<SERVER_IP> "docker run --rm -v gitea_gitea:/data -v \$(pwd):/backup ubuntu tar czf /backup/gitea_data.tar.gz /data"
```

## 故障排除

### 容器名稱有 -1 後綴

確保 `docker-compose.yml` 中每個服務都有 `container_name` 設定。

### 無法連接資料庫

確認網路設定正確，容器應在 `gitea` 網路中：

```bash
docker network inspect gitea_gitea
```

### SSH 連接失敗

確認 222 連接埠已開放，且 SSH 金鑰已正確添加到 Gitea 用戶設定。

## 升級

編輯 `docker-compose.yml` 更新映像版本後：

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