Gitea のバックアップとリストア：gitea dump の取り方と、戻すときの手順

ソースコードは、失われたら二度と同じものを作れない資産です。Gitea をセルフホストで運用するなら、バックアップは「いつかやる作業」ではなく、導入と同時に決めておく作業です。しかも、バックアップは取るだけでは意味がなく、戻せることを確かめて、はじめて役に立ちます。

この記事では、Gitea が用意している gitea dump というコマンドによるバックアップの取り方と、そこから戻す手順を説明します。確認した時点は2026年11月15日で、ドキュメントの最新の安定版は 28.3.0 です。

取っただけのバックアップは、安心にならない

バックアップの失敗は、取れていなかったことよりも、戻せなかったことで発覚するのが典型です。ドキュメントを読むと、戻すときに起こりうる問題が、いくつか明記されています。

• サービスを止めずに取ると、整合性が崩れます。 バックアップの途中で、データベースとリポジトリの内容が食い違うことがあります。ドキュメントは、取得の間は Gitea を停止しておく必要があると述べています。
• 戻す専用のコマンドがありません。 ダンプから戻す手順は、ファイルを所定の場所に移し、データベースを復元する、手動の作業です。慌てている障害の最中に、初めて手順を読んでも、うまくいきません。
• ダンプの SQL に、戻すときの問題が出ることがあります。 Gitea が出力する SQL は、XORM という仕組みを使っており、復元で問題が生じることがあります。そのため、データベースに付属する標準の道具を使う方法も案内されています。
• 移したあとに、フックを作り直さないと、push に失敗します。 インストールの方法が変わったとき（たとえば、バイナリから Docker へ）や、置き場所が変わったときは、フックの再生成が要ります。

これらを知らずにバックアップを運用していると、いざ戻す段階で時間を失います。逆に言えば、この四つを先に押さえ、一度試しておけば、備えとしては十分に実用的です。

バックアップの取り方

手順は、次のとおりです。

1. Gitea のサービスを停止します。
2. Gitea を動かしているユーザーに切り替えます（su git など）。
3. Gitea のインストール先で、ダンプを実行します。

./gitea dump -c /path/to/app.ini

実行すると、gitea-dump-1482906742.zip のような名前の ZIP ファイルが作られます。数字の部分は、実行した時刻を表します。途中経過のファイルは、--tempdir で指定したディレクトリか、環境変数 TMPDIR の場所に作られます。

ダンプに含まれるもの

ZIP ファイルの中身は、次のとおりです。

リポジトリ、データ、設定、データベースの四つがそろっているので、ひとつのファイルから、環境全体を復元できます。

データベースを別の道具でも取る

gitea dump が作る SQL の代わりに、データベース付属の道具を使うこともできます。

mysqldump -u$USER -p$PASS --database $DATABASE > gitea-db.sql
pg_dump -U $USER $DATABASE > gitea-db.sql

復元の問題を避けたい場合に、有効な手段です。ダンプとあわせて、この方法でも取っておくと、選択肢が増えます。

Docker で取る場合

Docker では、コマンドを実行するユーザーが重要です。ドキュメントによれば、app.ini の RUN_USER に設定されたユーザーで実行し、docker exec は --tempdir の中で実行する必要があります。

docker exec -u <OS_USERNAME> -it -w <--tempdir> $(docker ps -qf 'name=^<NAME_OF_DOCKER_CONTAINER>$') bash -c '/usr/local/bin/gitea dump -c </path/to/app.ini>'

山かっこの部分は、環境に合わせて置き換えます。

リストアの手順

戻す専用のコマンドはないため、次の手順を順に行います。

1. ダンプを展開する

unzip gitea-dump-1610949662.zip
cd gitea-dump-1610949662

2. ファイルを所定の場所へ移す

ドキュメントの例では、次のように移します。パスは、環境に合わせて読み替えます。

mv app.ini /etc/gitea/conf/app.ini
mv data/* /var/lib/gitea/data/
mv log/* /var/lib/gitea/log/
mv repos/* /var/lib/gitea/data/gitea-repositories/
chown -R gitea:gitea /etc/gitea/conf/app.ini /var/lib/gitea

3. データベースを復元する

使っているデータベースに合わせて、次のいずれかを実行します。

mysql --default-character-set=utf8mb4 -u$USER -p$PASS $DATABASE <gitea-db.sql
sqlite3 $DATABASE_PATH <gitea-db.sql
psql -U $USER -d $DATABASE < gitea-db.sql

MySQL では、文字セットに utf8mb4 を指定している点に注意してください。

4. 再起動する

service gitea restart

5. フックを再生成する

Gitea を起動した状態で、バイナリのあるディレクトリから、次を実行します。

./gitea admin regenerate hooks

この手順は、インストールの方法が変わった場合や、Gitea の置き場所が変わった場合に必要です。行わないと、リポジトリへの push が失敗することがあります。

6. 問題が残るとき

それでも問題があれば、診断のコマンドを使います。

./gitea doctor check

--fix を付けると、修復も試みます。

Docker で戻す場合

手順は同じで、パスがコンテナ内のものになります。docker exec --user git -it <コンテナ> bash でコンテナに入り、/data/gitea と /data/git/repositories/ に復元し、chown -R git:git /data で所有者を直します。フックの再生成は、/usr/local/bin/gitea -c '/data/gitea/conf/app.ini' admin regenerate hooks です。rootless のイメージでは、/etc/gitea/app.ini と /var/lib/gitea を使います。

別の種類のデータベースへの変換には頼らない

gitea dump には、--database <種類> で、別の種類のデータベース向けの SQL を出力する機能があります。ただし、ドキュメントは、この変換を十分にテストされていないものと位置づけています。データベースの種類を変えたいときは、あらかじめ完全なバックアップを取っておき、変換後の内容を丁寧に確認する必要があります。そもそも、種類を後から変えずに済むよう、最初の選択を慎重に行うのが望ましい進め方です。選び方は、データベースの選び方で整理しています。

運用に組み込むために

バックアップを、運用の習慣として定着させるには、次の点を決めておきます。

特に、保存先は大切です。バックアップを、動かしているサーバーと同じディスクにだけ置いていると、そのディスクの故障で、両方を同時に失います。別の機器、あるいは別の場所にも、コピーを置いておきます。

さらに、アップグレードの前にも、必ずバックアップを取ります。新しいバージョンの起動時には、データベースの構造が自動で書き換わり、古いバージョンに戻すには、バックアップから復元するしかないためです。進め方は、アップグレードの進め方で扱っています。

戻す練習を、平時に行っておく

復元の手順は、実際に一度行っておくことで、理解が深まります。練習の流れを、次に示します。

1. 試験用の環境を用意します。 本番とは別のマシンか、別のディレクトリに、Gitea を新しく用意します。
2. 本番のバックアップを、試験用の環境へ持ち込みます。 ZIP ファイルを展開し、ファイルを所定の場所に置き、データベースを復元します。
3. 起動して、確認します。 ログインできるか、リポジトリの一覧が表示されるか、いくつかのリポジトリで clone と push ができるかを確かめます。
4. フックを再生成します。 場所や方法が変わった場合は、gitea admin regenerate hooks を実行します。これを行わないと、push が失敗することがあります。
5. かかった時間を記録します。 復元に要した時間は、障害のときの、復旧までの目安になります。

この練習の結果は、手順書として残しておきます。ドキュメントの例とは、パスやユーザー名が異なるはずなので、自分たちの環境のものに書き換えた手順が、いちばん役に立ちます。

障害の種類ごとに、何から戻すか

障害の内容によって、必要な復旧の範囲は異なります。バックアップの構成要素を知っていれば、状況に応じた判断ができます。

一部だけを戻す場合は、データベースとリポジトリの整合が取れなくなるおそれがあります。判断に迷うときは、ダンプ全体を試験用の環境に復元し、そこから必要な部分を取り出す方法が安全です。

ダンプを取る時間と、保管の工夫

ダンプは、サービスを止めて取ります。そのため、止める時間を短くする工夫が、運用では重要になります。

• 利用が少ない時間帯に実行します。 夜間や休日など、影響の小さい時間を選びます。
• 事前に、利用者へ知らせます。 停止の時間帯を共有しておけば、混乱を避けられます。
• 自動化します。 手作業に頼ると、忘れたり、手順が人によって変わったりします。スクリプトにして、定期的に実行します。
• 世代を管理します。 直近のものだけでなく、数世代分を残します。問題に気づくまでに時間がかかった場合、直近のバックアップにも、問題が含まれていることがあるためです。

ダンプのファイルには、リポジトリの内容や、設定の情報が含まれます。保管場所のアクセス権を、適切に制限してください。

取得の前に、準備しておくこと

実際にダンプを取る前に、次の点を確認しておくと、作業が滞りません。

• 空き容量を確認します。 ダンプは、リポジトリのディレクトリの完全な写しを含むため、リポジトリの総量に近い容量が必要です。途中経過のファイルは --tempdir の場所に作られるので、そこにも余裕が必要です。
• 実行するユーザーを確認します。 Docker では、app.ini の RUN_USER のユーザーで実行する必要があります。違うユーザーで実行すると、ファイルを読み書きできない場合があります。
• 設定ファイルの場所を確認します。 -c で指定する app.ini のパスが、実際に使われているファイルと一致しているかを見ます。
• 停止の手順を確認します。 どのコマンドで止め、どのコマンドで再開するのかを、事前に決めておきます。

これらを、手順書に書き出しておけば、担当者が代わっても、同じ手順で実行できます。バックアップの取得と復元は、年に数回しか行わない作業でも、いざというときには、確実に実行できなければなりません。

バックアップを取れていることを、継続して確かめる

自動化したバックアップは、気づかないうちに止まっていることがあります。ディスクの容量不足や、権限の変更、パスの変更が、よくある原因です。そこで、取得そのものとは別に、確認の仕組みを用意します。

• 最新のダンプの日時とサイズを、定期的に確認します。サイズが極端に小さい場合は、取得に失敗している可能性があります。
• ZIP ファイルが、正しく展開できるかを確かめます。
• 月に一度など、日を決めて、試験用の環境へ復元してみます。

確認の結果は、簡単な記録として残します。記録があれば、「最後に戻せると確かめたのはいつか」が分かり、不安を減らせます。

保管するときの、もう一つの注意

ダンプのファイルは、サービスを止めて取った、ある時点の記録です。取得してから現在までの間に行われた変更は、含まれていません。そのため、復元すると、その後の変更は失われます。この差を小さくしたい場合は、取得の頻度を上げます。どこまでの期間の変更を失ってよいのかを、あらかじめ関係者と話し合っておくと、頻度を決めやすくなります。

戻せる状態を保つことが、運用の土台になる

バックアップの要点を、あらためてまとめます。

1. サービスを止めてから、gitea dump を実行します。
2. 出力された ZIP ファイルを、別の場所にも保管します。
3. 復元は手動の作業です。手順を、平時のうちに一度、試験用の環境で試しておきます。
4. 戻したあとは、フックを再生成し、必要に応じて gitea doctor check を実行します。

障害は、準備ができていないときに限って、起こるように感じられるものです。とはいえ、手順を一度通しておくだけで、実際の障害のときの落ち着きが違います。この記事の内容は、2026年11月15日時点のドキュメントに基づいています。パスやユーザー名は例なので、実際の環境に合わせて読み替え、試験用の環境で確認したうえで運用に取り入れていただくことをおすすめします。