gitea-deploy/skill.md

name, description, tools

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

Gitea Docker 部署

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

前置需求

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

部署步驟

Step 1: 建立目錄與配置

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: 啟動服務

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

Step 3: 驗證部署

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

其他設定可保持預設值。

常用指令

# 查看狀態
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 操作

備份

# 備份資料庫
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 網路中：

docker network inspect gitea_gitea

SSH 連接失敗

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

升級

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

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