OneDev 完整教程

所需空间 ≈ site 数据 + PostgreSQL 数据 + 构建工作区峰值
         + 本地镜像与缓存 + 两份完整恢复点 + 30% 余量

dig +short code.example.com A
dig +short code.example.com AAAA
curl -4 https://ifconfig.me

uname -a
docker version
docker compose version
free -h
df -hT / /opt /var/backups 2>/dev/null || true
sudo ss -lntp '( sport = :80 or sport = :443 or sport = :6610 or sport = :6611 )'

/opt/onedev/
├── compose.yaml
├── compose.bootstrap.yaml
├── compose.executor.yaml
├── compose.quiesced.yaml
├── .env
├── data/
└── postgres_data/

/etc/onedev/
└── secrets/
    ├── postgres_password
    └── admin_password

/var/backups/onedev/

sudo install -d -m 750 /opt/onedev/data /opt/onedev/postgres_data
sudo install -d -m 700 /etc/onedev/secrets /var/backups/onedev
openssl rand -hex 32 | sudo tee /etc/onedev/secrets/postgres_password >/dev/null
openssl rand -base64 36 | sudo tee /etc/onedev/secrets/admin_password >/dev/null
sudo chmod 600 /etc/onedev/secrets/postgres_password \
  /etc/onedev/secrets/admin_password

ONEDEV_IMAGE=1dev/server:16.4.2@sha256:ddb7e414e2e3038ab522ab4e517a95a5580cac0177ef5ee171fe37e4f209a34b
POSTGRES_IMAGE=postgres:16.14-alpine3.23@sha256:42b8b8b29c8a4e933d88943e5b03001a78794905cf786e6e7634e9f2abd5a0d3
ONEDEV_DOMAIN=code.example.com
ONEDEV_SSH_PORT=6611
ONEDEV_ADMIN_USER=admin
ONEDEV_ADMIN_EMAIL=admin@example.com
BACKUP_RETENTION_DAYS=14
TZ=Asia/Shanghai

name: onedev

services:
  postgres:
    image: ${POSTGRES_IMAGE:?POSTGRES_IMAGE is required}
    container_name: onedev-postgres
    restart: unless-stopped
    cpus: 1.0
    mem_limit: 768m
    shm_size: 256m
    volumes:
      - ./postgres_data:/var/lib/postgresql/data
    secrets:
      - postgres_password
    environment:
      POSTGRES_USER: onedev
      POSTGRES_DB: onedev
      POSTGRES_PASSWORD_FILE: /run/secrets/postgres_password
      PGDATA: /var/lib/postgresql/data
      TZ: ${TZ:-Asia/Shanghai}
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U onedev -d onedev"]
      interval: 10s
      timeout: 5s
      retries: 10
      start_period: 20s
    networks:
      - onedev
    logging:
      driver: local
      options:
        max-size: 50m
        max-file: "5"

  onedev:
    image: ${ONEDEV_IMAGE:?ONEDEV_IMAGE is required}
    container_name: onedev
    restart: always
    cpus: 2.0
    mem_limit: 2560m
    stop_grace_period: 2m
    ulimits:
      nofile:
        soft: 65536
        hard: 65536
    ports:
      - "127.0.0.1:6610:6610"
      - "${ONEDEV_SSH_BIND_HOST:-0.0.0.0}:${ONEDEV_SSH_PORT:-6611}:6611"
    volumes:
      - ./data:/opt/onedev
      - /var/backups/onedev:/var/backups/onedev
    secrets:
      - postgres_password
    environment:
      hibernate_dialect: io.onedev.server.persistence.PostgreSQLDialect
      hibernate_connection_driver_class: org.postgresql.Driver
      hibernate_connection_url: jdbc:postgresql://postgres:5432/onedev
      hibernate_connection_username: onedev
      hibernate_connection_password_file: /run/secrets/postgres_password
      TZ: ${TZ:-Asia/Shanghai}
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - onedev
    logging:
      driver: local
      options:
        max-size: 50m
        max-file: "5"

secrets:
  postgres_password:
    file: /etc/onedev/secrets/postgres_password

networks:
  onedev:
    driver: bridge

sudo chown root:root /opt/onedev/.env /opt/onedev/compose.yaml
sudo chmod 600 /opt/onedev/.env
sudo chmod 640 /opt/onedev/compose.yaml

services:
  onedev:
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

sudo chown root:root /opt/onedev/compose.executor.yaml
sudo chmod 640 /opt/onedev/compose.executor.yaml

cd /opt/onedev
sudo docker compose --env-file .env \
  -f compose.yaml \
  -f compose.executor.yaml \
  config --quiet
sudo docker compose --env-file .env \
  -f compose.yaml \
  -f compose.executor.yaml \
  pull

code.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:6610
}

sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile

services:
  onedev:
    secrets:
      - admin_password
    environment:
      initial_user: ${ONEDEV_ADMIN_USER:?ONEDEV_ADMIN_USER is required}
      initial_password_file: /run/secrets/admin_password
      initial_email: ${ONEDEV_ADMIN_EMAIL:?ONEDEV_ADMIN_EMAIL is required}
      initial_server_url: https://${ONEDEV_DOMAIN:?ONEDEV_DOMAIN is required}
      initial_ssh_root_url: ssh://${ONEDEV_DOMAIN:?ONEDEV_DOMAIN is required}:${ONEDEV_SSH_PORT:-6611}

secrets:
  admin_password:
    file: /etc/onedev/secrets/admin_password

sudo chown root:root /opt/onedev/compose.bootstrap.yaml
sudo chmod 640 /opt/onedev/compose.bootstrap.yaml

cd /opt/onedev
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
  -f compose.yaml \
  -f compose.bootstrap.yaml \
  -f compose.executor.yaml \
  up -d

curl --fail --retry 36 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:6610/ >/dev/null
sudo docker compose --env-file .env \
  -f compose.yaml \
  -f compose.bootstrap.yaml \
  -f compose.executor.yaml \
  logs --tail 100 onedev

sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
  -f compose.yaml \
  -f compose.executor.yaml \
  up -d --no-deps onedev
curl --fail --retry 36 --retry-delay 5 --retry-all-errors \
  http://127.0.0.1:6610/ >/dev/null

ssh_user=ubuntu
server_ip=203.0.113.20 # 替换为真实服务器地址
ssh -L 16610:127.0.0.1:6610 "${ssh_user}@${server_ip}"

sudo systemctl reload caddy
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
developer_cidr='203.0.113.0/24' # 替换为真实开发者出口 CIDR
sudo ufw allow from "${developer_cidr}" to any port 6611 proto tcp
sudo ufw status numbered

cd /opt/onedev
sudo docker compose --env-file .env \
  -f compose.yaml \
  -f compose.executor.yaml \
  up -d --no-deps onedev

curl -fsS https://code.example.com/ >/dev/null
ssh -T -p 6611 git@code.example.com

ssh-keygen -t ed25519 -C "onedev-code" -f ~/.ssh/id_ed25519_onedev
cat ~/.ssh/id_ed25519_onedev.pub

mkdir hello && cd hello
go mod init example.com/hello

package main

import (
	"fmt"
	"log"
	"net/http"
)

func main() {
	log.Fatal(http.ListenAndServe(":8080", newHandler()))
}

func newHandler() http.Handler {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.URL.Path != "/" {
			http.NotFound(w, r)
			return
		}
		_, _ = fmt.Fprintln(w, "hello from OneDev")
	})
	mux.HandleFunc("/healthz", func(w http.ResponseWriter, _ *http.Request) {
		_, _ = fmt.Fprintln(w, "ok")
	})
	return mux
}

package main

import (
	"net/http"
	"net/http/httptest"
	"strings"
	"testing"
)

func TestHealthResponse(t *testing.T) {
	recorder := httptest.NewRecorder()
	request := httptest.NewRequest(http.MethodGet, "/healthz", nil)
	newHandler().ServeHTTP(recorder, request)

	if recorder.Code != http.StatusOK || strings.TrimSpace(recorder.Body.String()) != "ok" {
		t.Fatalf("unexpected response: code=%d body=%q", recorder.Code, recorder.Body.String())
	}
}

FROM golang:1.24-alpine@sha256:8bee1901f1e530bfb4a7850aa7a479d17ae3a18beb6e09064ed54cfd245b7191 AS build
WORKDIR /src
COPY go.mod ./
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go test ./... \
    && CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/hello .

FROM alpine:3.22@sha256:14358309a308569c32bdc37e2e0e9694be33a9d99e68afb0f5ff33cc1f695dce
RUN addgroup -S app && adduser -S -G app app
COPY --from=build /out/hello /usr/local/bin/hello
USER app
EXPOSE 8080
ENTRYPOINT ["/usr/local/bin/hello"]

git init
git add .
git commit -m "Add hello service"
git branch -M main
git remote add origin ssh://git@code.example.com:6611/demo/hello.git
GIT_SSH_COMMAND='ssh -i ~/.ssh/id_ed25519_onedev -o IdentitiesOnly=yes' \
  git push -u origin main

version: 52

jobs:
  - name: CI
    jobExecutor: trusted-local-docker
    steps:
      - type: CheckoutStep
        name: checkout
        cloneCredential:
          type: DefaultCredential
        withLfs: false
        withSubmodules: false
        condition: SUCCESSFUL
        optional: false

      - type: CommandStep
        name: test and build
        runInContainer: true
        image: golang:1.24-alpine@sha256:8bee1901f1e530bfb4a7850aa7a479d17ae3a18beb6e09064ed54cfd245b7191
        interpreter:
          type: PosixInterpreter
          shell: sh
          commands: |
            set -eu
            go test ./...
            mkdir -p dist
            CGO_ENABLED=0 GOOS=linux go build \
              -trimpath -ldflags="-s -w" -o dist/hello .
        useTTY: false
        runAs: 0:0
        condition: SUCCESSFUL
        optional: false

      - type: PublishArtifactStep
        name: publish binary
        artifacts: dist/**
        condition: SUCCESSFUL
        optional: false

    triggers:
      - type: BranchUpdateTrigger
        branches: main
        userMatch: anyone
    retryCondition: never
    maxRetries: 0
    timeout: 600

git add .onedev-buildspec.yml
git commit -m "Add OneDev CI"
git push

sudo install -d -m 750 -o root -g root /opt/hello

name: hello

services:
  app:
    image: ${APP_IMAGE:?APP_IMAGE is required}
    container_name: hello
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    logging:
      driver: local
      options:
        max-size: 20m
        max-file: "5"

APP_IMAGE=

printf '%s' '<PACKAGE_READ_TOKEN>' | \
  sudo docker login code.example.com \
    --username deploy-reader \
    --password-stdin

ssh-keygen -t ed25519 -f ./hello-deploy-key -C 'onedev hello deploy'

id -u hello-deploy >/dev/null 2>&1 || \
  sudo useradd --create-home --user-group --shell /bin/bash hello-deploy
sudo passwd -l hello-deploy
sudo install -d -m 700 -o hello-deploy -g hello-deploy /home/hello-deploy/.ssh
sudoedit /home/hello-deploy/.ssh/authorized_keys
sudo chown hello-deploy:hello-deploy /home/hello-deploy/.ssh/authorized_keys
sudo chmod 600 /home/hello-deploy/.ssh/authorized_keys

#!/usr/bin/env bash
set -Eeuo pipefail

if [ "$#" -ne 1 ]; then
  echo "usage: deploy-hello <image@sha256:digest>" >&2
  exit 2
fi

release_ref="$1"
allowed_repo=code.example.com/demo/hello/app
install_root=/opt/hello
env_file="${install_root}/release.env"
lock_file=/run/lock/hello-deploy.lock

digest="${release_ref#"${allowed_repo}@sha256:"}"
if [ "${release_ref}" != "${allowed_repo}@sha256:${digest}" ] \
  || ! [[ "${digest}" =~ ^[a-f0-9]{64}$ ]]; then
  echo "release image must use an exact sha256 digest" >&2
  exit 3
fi

exec 9>"${lock_file}"
flock -n 9 || {
  echo "another deployment is running" >&2
  exit 4
}

write_release() {
  local ref="$1" next
  next="$(mktemp "${install_root}/.release.env.XXXXXX")"
  printf 'APP_IMAGE=%s\n' "${ref}" >"${next}"
  chmod 600 "${next}"
  mv "${next}" "${env_file}"
}

wait_for_health() {
  local attempt
  for attempt in $(seq 1 30); do
    if curl -fsS http://127.0.0.1:8080/healthz >/dev/null; then
      return 0
    fi
    sleep 2
  done
  return 1
}

cd "${install_root}"
if ! current_ref="$(awk -F= '
  $1 == "APP_IMAGE" {
    count++
    value = substr($0, index($0, "=") + 1)
  }
  END {
    if (count != 1) exit 1
    print value
  }
' "${env_file}")"; then
  echo "release.env must contain exactly one APP_IMAGE entry" >&2
  exit 5
fi

previous_available=0
if docker inspect hello >/dev/null 2>&1; then
  current_digest="${current_ref#"${allowed_repo}@sha256:"}"
  if [ "${current_ref}" != "${allowed_repo}@sha256:${current_digest}" ] \
    || ! [[ "${current_digest}" =~ ^[a-f0-9]{64}$ ]]; then
    echo "current release is not recoverable" >&2
    exit 6
  fi
  if ! wait_for_health; then
    echo "current release is not healthy; deployment refused" >&2
    exit 7
  fi
  previous_available=1
elif [ -n "${current_ref}" ]; then
  echo "release.env declares an image but the application container is absent" >&2
  exit 8
fi

rollback_required=0
rollback() {
  local exit_code=$?
  trap - EXIT
  if [ "${rollback_required}" -eq 1 ]; then
    if [ "${previous_available}" -eq 1 ]; then
      write_release "${current_ref}"
      docker compose --env-file "${env_file}" up -d --no-deps app \
        || exit_code=1
      wait_for_health || exit_code=1
    else
      docker compose --env-file "${env_file}" down --remove-orphans \
        || exit_code=1
      write_release ""
    fi
  fi
  exit "${exit_code}"
}
trap rollback EXIT

write_release "${release_ref}"
rollback_required=1
docker compose --env-file "${env_file}" pull app
docker compose --env-file "${env_file}" up -d --no-deps app
wait_for_health

running_ref="$(docker inspect hello --format '{{.Config.Image}}')"
test "${running_ref}" = "${release_ref}"
rollback_required=0
trap - EXIT
echo "deployed ${release_ref}"

sudo chown root:root /usr/local/sbin/deploy-hello
sudo chmod 750 /usr/local/sbin/deploy-hello
sudo chown root:root /opt/hello/compose.yaml /opt/hello/release.env
sudo chmod 640 /opt/hello/compose.yaml
sudo chmod 600 /opt/hello/release.env
printf '%s\n' \
  'hello-deploy ALL=(root) NOPASSWD: /usr/local/sbin/deploy-hello *' \
  | sudo tee /etc/sudoers.d/hello-deploy >/dev/null
sudo chmod 440 /etc/sudoers.d/hello-deploy
sudo visudo -cf /etc/sudoers.d/hello-deploy
sudo /usr/local/sbin/deploy-hello \
  'code.example.com/demo/hello/app@sha256:<64位摘要>'

app.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:8080
}

sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl reload caddy
curl -fsS https://app.example.com/ >/dev/null
curl -fsS https://app.example.com/healthz

# 生产机可信控制台
sudo ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

# 管理员电脑
ssh-keyscan -H -p 22 app.example.com >hello-known-hosts
ssh-keygen -lf hello-known-hosts

command -v bash docker jq ssh
docker buildx version

  - name: Deploy Production
    jobExecutor: trusted-local-docker
    steps:
      - type: CheckoutStep
        name: checkout
        cloneCredential:
          type: DefaultCredential
        withLfs: false
        withSubmodules: false
        condition: SUCCESSFUL
        optional: false

      - type: CommandStep
        name: build image and deploy digest
        runInContainer: false
        interpreter:
          type: DefaultInterpreter
          commands: |
            bash <<'BASH'
            set -Eeuo pipefail

            REGISTRY='@property:registry_host@'
            REPOSITORY='@property:registry_repository@'
            USERNAME='@property:registry_username@'
            ACCESS_TOKEN="$(cat <<'ONEDEV_SECRET'
            @secret:registry_access_token@
            ONEDEV_SECRET
            )"
            DEPLOY_HOST='@property:deploy_host@'
            DEPLOY_USER='@property:deploy_user@'
            DEPLOY_PORT='@property:deploy_port@'
            COMMIT='@commit_hash@'
            IMAGE="${REGISTRY}/${REPOSITORY}"

            docker_config="$(mktemp -d)"
            builder_name="onedev-${COMMIT:0:12}-$$"
            key_file="$(mktemp)"
            known_hosts_file="$(mktemp)"
            metadata_file="$(mktemp)"
            cleanup() {
              docker buildx rm "${builder_name}" >/dev/null 2>&1 || true
              rm -rf -- "${docker_config}"
              rm -f "${key_file}" "${known_hosts_file}" "${metadata_file}"
            }
            trap cleanup EXIT
            trap 'exit 129' HUP
            trap 'exit 130' INT
            trap 'exit 143' TERM
            export DOCKER_CONFIG="${docker_config}"

            cat >"${key_file}" <<'ONEDEV_SSH_KEY'
            @secret:deploy_ssh_key@
            ONEDEV_SSH_KEY
            cat >"${known_hosts_file}" <<'ONEDEV_KNOWN_HOSTS'
            @secret:deploy_known_hosts@
            ONEDEV_KNOWN_HOSTS
            chmod 600 "${key_file}" "${known_hosts_file}"

            printf '%s' "${ACCESS_TOKEN}" | docker login "${REGISTRY}" \
              -u "${USERNAME}" --password-stdin
            unset ACCESS_TOKEN
            docker buildx create \
              --name "${builder_name}" \
              --driver docker-container \
              --use >/dev/null
            docker buildx inspect --bootstrap >/dev/null
            docker buildx build \
              --platform linux/amd64 \
              --push \
              --tag "${IMAGE}:${COMMIT}" \
              --metadata-file "${metadata_file}" \
              .

            DIGEST="$(jq -er '."containerimage.digest"' "${metadata_file}")"
            RELEASE_REF="${IMAGE}@${DIGEST}"
            printf '%s\n' "${RELEASE_REF}" >release-ref.txt
            printf 'deploying %s\n' "${RELEASE_REF}"
            REMOTE="${DEPLOY_USER}@@${DEPLOY_HOST}"
            release_ref_q="$(printf '%q' "${RELEASE_REF}")"

            ssh -i "${key_file}" \
              -o "UserKnownHostsFile=${known_hosts_file}" \
              -o StrictHostKeyChecking=yes \
              -p "${DEPLOY_PORT}" \
              "${REMOTE}" \
              "sudo /usr/local/sbin/deploy-hello ${release_ref_q}"
            BASH
        useTTY: false
        condition: SUCCESSFUL
        optional: false

      - type: PublishArtifactStep
        name: publish release identity
        artifacts: release-ref.txt
        condition: SUCCESSFUL
        optional: false

    jobDependencies:
      - jobName: CI
        requireSuccessful: true
        artifacts: "**"
    triggers:
      - type: DependencyFinishedTrigger
    retryCondition: never
    maxRetries: 0
    timeout: 1800

networks:
  onedev:
    internal: true

sudo chown root:root /opt/onedev/compose.quiesced.yaml
sudo chmod 640 /opt/onedev/compose.quiesced.yaml

cd /opt/onedev
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    config --quiet

#!/usr/bin/env bash
set -Eeuo pipefail

install_root=/opt/onedev
backup_root=/var/backups/onedev
env_file="${install_root}/.env"
compose_file="${install_root}/compose.yaml"
executor_file="${install_root}/compose.executor.yaml"
upgrade_journal=/var/lib/onedev-upgrade/active.env
admin_password_file=/etc/onedev/secrets/admin_password

for command in awk base64 curl docker find flock install mv seq sha256sum stat sync tar tr; do
  command -v "${command}" >/dev/null 2>&1 || {
    echo "missing command: ${command}" >&2
    exit 2
  }
done
docker compose version >/dev/null
for file in \
  "${env_file}" \
  "${compose_file}" \
  "${executor_file}" \
  /opt/onedev/compose.bootstrap.yaml \
  /opt/onedev/compose.quiesced.yaml; do
  test -f "${file}"
  test ! -L "${file}"
done

compose() {
  docker compose --env-file "${env_file}" \
    -f "${compose_file}" \
    -f "${executor_file}" "$@"
}

wait_for_onedev() {
  local attempt
  for attempt in $(seq 1 60); do
    if curl -fsS http://127.0.0.1:6610/ >/dev/null; then
      return 0
    fi
    sleep 3
  done
  return 1
}

exec 9>/run/lock/onedev-lifecycle.lock
flock -n 9 || {
  echo "another OneDev lifecycle operation is running" >&2
  exit 3
}

if [ -e "${upgrade_journal}" ] || [ -L "${upgrade_journal}" ]; then
  echo "an upgrade transaction is active" >&2
  exit 4
fi

retention_days="$(awk -F= '
  $1 == "BACKUP_RETENTION_DAYS" {
    count++
    value = substr($0, index($0, "=") + 1)
  }
  END {
    if (count != 1) exit 1
    print value
  }
' "${env_file}")"
if ! [[ "${retention_days}" =~ ^[0-9]+$ ]] \
  || [ "${retention_days}" -lt 1 ] \
  || [ "${retention_days}" -gt 365 ]; then
  echo "BACKUP_RETENTION_DAYS must be between 1 and 365" >&2
  exit 5
fi

admin_user="$(awk -F= '
  $1 == "ONEDEV_ADMIN_USER" {
    count++
    value = substr($0, index($0, "=") + 1)
  }
  END {
    if (count != 1) exit 1
    print value
  }
' "${env_file}")"
if [ -z "${admin_user}" ] \
  || [ ! -f "${admin_password_file}" ] \
  || [ -L "${admin_password_file}" ] \
  || [ ! -s "${admin_password_file}" ] \
  || [ "$(stat -c '%u:%a' "${admin_password_file}")" != "0:600" ]; then
  echo "managed OneDev administrator credential is missing" >&2
  exit 6
fi
basic_token="$(
  printf '%s:%s' "${admin_user}" "$(<"${admin_password_file}")" \
    | base64 | tr -d '\n'
)"
if ! printf '%s\n' \
  'silent' \
  'show-error' \
  'fail-with-body' \
  'connect-timeout = 5' \
  'max-time = 30' \
  "header = \"Authorization: Basic ${basic_token}\"" \
  'header = "Accept: application/json"' \
  | curl --config - --output /dev/null \
      http://127.0.0.1:6610/~api/settings/system; then
  unset basic_token
  echo "managed OneDev administrator credential is invalid" >&2
  exit 7
fi
unset basic_token

timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
incomplete="${backup_root}/.${timestamp}.incomplete"
final="${backup_root}/${timestamp}"
[[ "${timestamp}" =~ ^20[0-9]{6}T[0-9]{6}Z$ ]]
if [ -e "${incomplete}" ] || [ -L "${incomplete}" ] \
  || [ -e "${final}" ] || [ -L "${final}" ]; then
  echo "backup target already exists: ${timestamp}" >&2
  exit 8
fi

restart_required=0
cleanup_backup() {
  local exit_code=$?
  trap - EXIT
  if [ "${restart_required}" -eq 1 ]; then
    compose up -d onedev || exit_code=1
    wait_for_onedev || exit_code=1
  fi
  if [[ "${incomplete}" =~ ^/var/backups/onedev/\.20[0-9]{6}T[0-9]{6}Z\.incomplete$ ]] \
    && [ -d "${incomplete}" ]; then
    rm -rf -- "${incomplete}"
  fi
  exit "${exit_code}"
}
trap cleanup_backup EXIT
trap 'exit 130' INT
trap 'exit 143' TERM

install -d -m 700 "${incomplete}"
cd "${install_root}"

restart_required=1
compose stop --timeout 120 onedev
compose run --rm --no-deps \
  --entrypoint /opt/onedev/bin/backup-db.sh \
  onedev "/var/backups/onedev/$(basename "${incomplete}")/database.zip"

tar --numeric-owner -C "${install_root}/data" \
  -czf "${incomplete}/site.tar.gz" site
tar --numeric-owner -C / -czf "${incomplete}/configuration.tar.gz" \
  etc/onedev \
  opt/onedev/compose.yaml \
  opt/onedev/compose.bootstrap.yaml \
  opt/onedev/compose.executor.yaml \
  opt/onedev/compose.quiesced.yaml \
  opt/onedev/.env

(
  cd "${incomplete}"
  sha256sum database.zip site.tar.gz configuration.tar.gz >SHA256SUMS
  sha256sum -c SHA256SUMS
)
sync -f "${incomplete}"

compose up -d onedev
wait_for_onedev
restart_required=0

mv "${incomplete}" "${final}"
sync -f "${final}"
sync -f "${backup_root}"
trap - EXIT
printf 'backup complete: %s\n' "${final}"

while IFS= read -r expired; do
  name="$(basename "${expired}")"
  if [[ "${name}" =~ ^20[0-9]{6}T[0-9]{6}Z$ ]]; then
    rm -rf -- "${expired}"
  fi
done < <(
  find "${backup_root}" \
    -mindepth 1 \
    -maxdepth 1 \
    -type d \
    -name '20??????T??????Z' \
    -mtime "+${retention_days}" \
    -print
)

sudo chown root:root /usr/local/sbin/onedev-backup
sudo chmod 750 /usr/local/sbin/onedev-backup
sudo /usr/local/sbin/onedev-backup

[Unit]
Description=OneDev database and site backup
After=docker.service
Requires=docker.service
ConditionPathExists=!/var/lib/onedev-upgrade/active.env

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/onedev-backup
Nice=10
IOSchedulingClass=best-effort
IOSchedulingPriority=7

[Unit]
Description=Daily OneDev backup

[Timer]
OnCalendar=*-*-* 03:30:00
Persistent=true
RandomizedDelaySec=10m
Unit=onedev-backup.service

[Install]
WantedBy=timers.target

sudo systemctl daemon-reload
sudo systemctl enable --now onedev-backup.timer
sudo systemctl start onedev-backup.service
sudo systemctl status onedev-backup.service --no-pager
sudo systemctl list-timers onedev-backup.timer --no-pager

database.zip
site.tar.gz
configuration.tar.gz
SHA256SUMS

sudo bash <<'BASH'
set -Eeuo pipefail

backup_id=20260903T033000Z # 替换为准备恢复的 UTC 时间戳
backup_root=/var/backups/onedev
backup_dir="${backup_root}/${backup_id}"

if ! [[ "${backup_id}" =~ ^20[0-9]{6}T[0-9]{6}Z$ ]] \
  || [ ! -d "${backup_dir}" ] \
  || [ -L "${backup_dir}" ]; then
  echo "invalid backup directory" >&2
  exit 2
fi

for file in database.zip site.tar.gz configuration.tar.gz SHA256SUMS; do
  test -f "${backup_dir}/${file}"
  test ! -L "${backup_dir}/${file}"
done

awk '
  NF != 2 || length($1) != 64 || $1 !~ /^[0-9a-f]+$/ { exit 1 }
  $2 != "database.zip" && $2 != "site.tar.gz" && $2 != "configuration.tar.gz" { exit 1 }
  seen[$2]++ { exit 1 }
  END {
    if (NR != 3 || !seen["database.zip"] || !seen["site.tar.gz"] || !seen["configuration.tar.gz"])
      exit 1
  }
' "${backup_dir}/SHA256SUMS"

(
  cd "${backup_dir}"
  sha256sum -c SHA256SUMS
)

validate_archive() {
  local archive="$1" allowed="$2"
  tar -tvzf "${archive}" | awk '
    substr($1, 1, 1) != "d" && substr($1, 1, 1) != "-" { exit 1 }
  '
  while IFS= read -r entry; do
    if [[ "${entry}" = /* ]] || [[ "/${entry}/" = *"/../"* ]] \
      || ! [[ "${entry}" =~ ${allowed} ]]; then
      echo "archive contains an unexpected path: ${entry}" >&2
      return 1
    fi
  done < <(tar -tzf "${archive}")
}

validate_archive \
  "${backup_dir}/site.tar.gz" \
  '^site(/.*)?$'
validate_archive \
  "${backup_dir}/configuration.tar.gz" \
  '^etc/onedev(/.*)?$|^opt/onedev/(compose(\.(bootstrap|executor|quiesced))?\.yaml|\.env)$'

for target in \
  /etc/onedev \
  /opt/onedev \
  /var/lib/onedev-upgrade \
  /usr/local/sbin/onedev-backup \
  /etc/systemd/system/onedev-backup.service \
  /etc/systemd/system/onedev-backup.timer \
  /etc/caddy/sites/onedev.caddy; do
  if [ -e "${target}" ] || [ -L "${target}" ]; then
    echo "restore target is not empty: ${target}" >&2
    exit 3
  fi
done
if docker inspect onedev >/dev/null 2>&1 \
  || docker inspect onedev-postgres >/dev/null 2>&1; then
  echo "OneDev containers already exist" >&2
  exit 4
fi

install -d -m 750 /opt/onedev/data /opt/onedev/postgres_data
tar --numeric-owner -xzf "${backup_dir}/configuration.tar.gz" -C /
tar --numeric-owner -xzf "${backup_dir}/site.tar.gz" -C /opt/onedev/data
chmod 600 /opt/onedev/.env /etc/onedev/secrets/*
chmod 640 \
  /opt/onedev/compose.yaml \
  /opt/onedev/compose.bootstrap.yaml \
  /opt/onedev/compose.executor.yaml \
  /opt/onedev/compose.quiesced.yaml
BASH

cd /opt/onedev
backup_id=20260903T033000Z # 替换为已经校验的恢复点
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    up -d postgres
for attempt in $(seq 1 30); do
  if sudo docker exec onedev-postgres \
    pg_isready -U onedev -d onedev >/dev/null 2>&1; then
    break
  fi
  if [ "${attempt}" -eq 30 ]; then
    echo "PostgreSQL did not become ready" >&2
    exit 1
  fi
  sleep 2
done
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    run --rm --no-deps \
      --entrypoint /bin/bash \
      onedev -ceu '
        case "$(uname -m)" in
          aarch64|arm64) cpu_arch=arm-64 ;;
          x86_64|amd64) cpu_arch=x86-64 ;;
          *) echo "unsupported architecture: $(uname -m)" >&2; exit 1 ;;
        esac
        "/app/boot/wrapper-linux-${cpu_arch}" \
          /app/conf/wrapper.conf \
          -- upgrade /opt/onedev
        touch /opt/onedev/IN_DOCKER
        test -x /opt/onedev/bin/restore-db.sh
      '
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    run --rm --no-deps \
      --entrypoint /opt/onedev/bin/restore-db.sh \
      onedev "/var/backups/onedev/${backup_id}/database.zip"
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    up -d onedev
curl --fail --retry 60 --retry-delay 3 --retry-all-errors \
  http://127.0.0.1:6610/ >/dev/null

cd /opt/onedev
sudo env ONEDEV_SSH_BIND_HOST=127.0.0.1 \
  docker compose --env-file .env \
    -f compose.yaml \
    -f compose.quiesced.yaml \
    down --remove-orphans
sudo docker compose --env-file .env \
  -f compose.yaml \
  -f compose.executor.yaml \
  up -d
sudo systemctl enable --now onedev-backup.timer
sudo systemctl reload caddy
curl -fsS https://code.example.com/ >/dev/null
ssh -T -p 6611 git@code.example.com

核对当前实例与目标 tag/digest
→ 确认没有 waiting、pending、running 构建
→ 检查磁盘足够保存目标镜像和至少两份恢复点
→ HTTPS 返回维护响应，Git SSH 与本机构建停止接收新写入
→ 使用当前版本生成并校验完整恢复点
→ 在无公网端口、无 Docker socket、internal 网络中切换目标镜像
→ 从容器内部验证目标版本、数据库和数据目录
→ 生成升级后的完整恢复点
→ 持久提交新版本
→ 重建正常网络，恢复 Git SSH 与 HTTPS
→ 重新检查 HTTPS、Git SSH、构建、备份和运行镜像

cd /opt/onedev
sudo docker compose --env-file .env \
  -f compose.yaml -f compose.executor.yaml ps
sudo docker compose --env-file .env \
  -f compose.yaml -f compose.executor.yaml \
  logs --tail 200 postgres onedev
sudo docker inspect onedev --format 'ref={{.Config.Image}} id={{.Image}}'
sudo docker inspect onedev-postgres --format '{{json .State.Health}}'
sudo ss -lntp '( sport = :80 or sport = :443 or sport = :6610 or sport = :6611 )'
curl -fsS http://127.0.0.1:6610/ >/dev/null
curl -fsS https://code.example.com/ >/dev/null
ssh -T -p 6611 git@code.example.com
sudo caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile
sudo systemctl status caddy
sudo systemctl status onedev-backup.timer