この記事は「読んで分かる」だけでなく、同じ手順をなぞれば実際に移行できる粒度で書いてある。AI エージェントに実行させる場合の注意点は最後の節にまとめた。
| Step | やること | 入力 | 出力 | 失敗したとき |
|---|---|---|---|---|
| 1 | GROWI の DB からデータを書き出す(読み取りのみ) | GROWI の MongoDB | export/*.jsonl |
何も壊れていない。やり直すだけ |
| 2 | 変換(書き込みなし) | export/*.jsonl |
build/pages_import.jsonl ほか |
同上。変換ルールを直して再実行 |
| 3 | ページを投入 | build/pages_import.jsonl |
wiki.js のページ | 途中で止まっても、存在チェックで続きから再開できる |
| 4 | 添付を投入 | build/assets_upload.jsonl + 実ファイル |
wiki.js の添付 | 同上 |
| 5 | 非公開ページの権限を設定 | 非公開ページ一覧 | Guests の拒否ルール | ルールは決定的に作り直せる |
| 6 | 検証(ゲスト目線) | 全 URL | 検証ログ(不一致 0 が合格) | 不一致の URL を直して再検証 |
| 7 | 公開(切替) | 移行先 wiki.js | 公開サイト | リバースプロキシを戻せば元のサイトに復帰 |
Step 7 までは本番に影響しない。 元のサイトは動かしたまま、裏で新しい Wiki を育てられる。
urllib と concurrent.futures しか使わない)記事中で使う記号は各自の環境に読み替える。
| 記号 | 意味 |
|---|---|
<API_BASE> |
wiki.js のベース URL(例: http://<wiki-host>:<port>) |
<API_KEY> |
発行した API キー(記事やリポジトリに書かない。環境変数で渡す) |
<MONGO_CONTAINER> |
GROWI の MongoDB コンテナ名 |
<GROWI_DB> |
GROWI のデータベース名 |
<GROWI_UPLOADS_DIR> |
GROWI の添付ファイル実体があるディレクトリ |
<DB_CONTAINER> / <DB_USER> / <DB_NAME> |
移行先 PostgreSQL(コンテナ・ユーザー・DB 名) |
<WIKI_DATA_DIR> |
wiki.js の添付保存領域(コンテナ内のパス) |
作業ディレクトリは次の構成にすると、途中で何度失敗しても追いやすい。
migration/
├── export/ # Step1: GROWI からの書き出し(触らない)
├── build/ # Step2: 変換結果とログ
└── scripts/ # ダンプ・変換・投入・権限・検証のスクリプト
GROWI は本文を MongoDB の pages / revisions に、タグを tags / pagetagrelations に、添付を attachments に持っている。管理画面のエクスポート機能より、DB から直接読み出した方が確実だ(ページ階層・タグ・添付のメタ情報が一度に取れる)。
dump_pages.js(ページ+本文+タグ。status が published のものだけ出す):
/* Dump all live GROWI pages as JSONL for the wiki.js migration */
var tagById = {};
db.tags.find({}).forEach(function (t) { tagById[String(t._id)] = t.name; });
var relByPage = {};
db.pagetagrelations.find({}).forEach(function (r) {
var k = String(r.pageId);
relByPage[k] = relByPage[k] || [];
if (tagById[String(r.tagId)]) relByPage[k].push(tagById[String(r.tagId)]);
});
db.pages.find({ status: "published" }).sort({ path: 1 }).forEach(function (p) {
var rev = db.revisions.findOne({ _id: p.revision });
print(JSON.stringify({
id: String(p._id),
path: p.path,
grant: p.grant, // 1 = 公開 / それ以外 = 非公開扱い
createdAt: p.createdAt,
updatedAt: p.updatedAt,
tags: relByPage[String(p._id)] || [],
body: rev ? rev.body : "",
bodyFormat: rev ? rev.format : null
}));
});
dump_attachments.js(添付のメタ情報):
/* Dump GROWI attachment metadata as JSONL */
db.attachments.find({}).forEach(function (a) {
print(JSON.stringify({
id: String(a._id),
fileName: a.fileName,
originalName: a.originalName || null,
fileFormat: a.fileFormat || null,
fileSize: a.fileSize,
createdAt: a.createdAt,
page: a.page ? String(a.page) : null
}));
});
実行例(コンテナの中の mongosh に流す。--quiet を付けないとログが混ざる):
docker exec -i <MONGO_CONTAINER> mongosh <GROWI_DB> --quiet --file /dev/stdin \
< scripts/dump_pages.js > export/growi_pages.jsonl
docker exec -i <MONGO_CONTAINER> mongosh <GROWI_DB> --quiet --file /dev/stdin \
< scripts/dump_attachments.js > export/growi_attachments.jsonl
確認: wc -l export/*.jsonl が GROWI の画面のページ数・添付数と一致していること。ここでズレていたら先に進まない(後段の検証が意味を失う)。
ここが一番「知恵」が要る工程。1つのルールにつき1つの関数にして、件数を数えながら進めると後で揉めない。
| 変換 | なぜ | どう直す |
|---|---|---|
| パスの空白・「.」 | wiki.js はこの2文字をパスに使えない | _ に置換(旧新の対応表を TSV で残す) |
| 添付リンク | URL 形式が違う | /attachment/<24桁ID> → /<fileName> |
目次(@[toc]) |
wiki.js に無い | パネル型・表型・単独行の3パターンを消す(表のヘッダと区切り行も一緒に) |
子ページ一覧($lsx()) |
wiki.js に無い | その行と、直前の表の飾りを消す |
[[ページ名]] |
wiki.js の記法ではない | リンク先が見つかったときだけ [表示名](/パス) に変換 |
@[名前] |
GROWI のメンション記法 | @名前 に直す |
末尾の #タグ 行 |
GROWI のタグ記法 | ページのタグとして登録し、本文からは外す |
| 本文が空のページ | 存在ごと見失う | 「本文は空でした」のメモを入れて作る |
実際に使った変換の要点(標準ライブラリだけで動く):
import re, json
ATTACH_RE = re.compile(r"/attachment/([0-9a-f]{24})")
PANEL_TOC_RE = re.compile(
r'<div class="panel[^"]*">\s*<div class="panel-heading">\s*Contents\s*</div>\s*'
r'<div class="panel-body">\s*@\[toc\]\s*</div>\s*</div>\s*\n?')
def norm_path(src: str) -> str:
p = src.strip().lstrip("/").replace("\\", "")
while "//" in p:
p = p.replace("//", "")
return "home" if p == "" else p.replace(" ", "_").replace(".", "_")
def transform(page, attachments, link_index):
body = page["body"]
# 1) 添付リンクを wiki.js 形式へ
body = ATTACH_RE.sub(lambda m: "/" + attachments[m.group(1)]["fileName"]
if m.group(1) in attachments else m.group(0), body)
# 2) 目次を消す(パネル型 → 行型)
body = PANEL_TOC_RE.sub("", body)
out = []
for line in body.split("\n"):
if "@[toc]" in line:
# 表の中の目次なら、ヘッダ行と区切り行も一緒に落とす
if len(out) >= 2 and re.match(r"^\|[\s\-|:]+$", out[-1].strip()) \
and re.match(r"^\|\s*Contents", out[-2], re.I):
out.pop(); out.pop()
continue
if "$lsx(" in line:
while out and re.match(r"^\|[\s\-|:]*\|$", out[-1].strip()):
out.pop()
continue
out.append(line)
body = "\n".join(out).replace("@[toc]", "")
# 3) リンクとメンション
body = re.sub(r"\[\[([^\]]+)\]\]",
lambda m: f"[{m.group(1)}](/{link_index[m.group(1)]})"
if m.group(1) in link_index else m.group(0), body)
body = re.sub(r"@\[([^\]\[]+)\]", lambda m: "@" + m.group(1), body)
# 4) 空ページの補完
if not body.strip():
body = f"*(GROWI側「{page['path']}」の本文は空でした)*\n"
return norm_path(page["path"]), body
リンク解決のために、変換の前に旧パス→新パスの索引を作っておく(末尾セグメント名と、先頭スラッシュ無しのフルパスを両方登録する)。
投入前の自己検証(ここで止めれば、汚いデータを wiki.js に入れずに済む):
Counter で数える). 空白 \ //)が残っていないか実測の集計例(report.txt):
pages: 317
path renames (space or dot): 45
duplicate paths after transform: []
paths still illegal for wiki.js: []
empty pages: []
attachment links rewritten: 239
lsx plugin tables removed: 149
toc lines removed: 268
attachments to upload: 407 files / 408.0 MiB
private pages: 41
出力する成果物は4つ。build/pages_import.jsonl(投入レコード)、build/rename_map.tsv(パス変更の対応表)、build/assets_upload.jsonl(投入する添付一覧)、build/report.txt(集計)。
方針は「先に既存パスを全部取って、無いものだけ作る」。何度実行しても二重作成しない。
import concurrent.futures, json, os, threading, urllib.request
BASE, KEY, LOCALE = "<API_BASE>", os.environ["WIKIJS_API_KEY"], "ja"
CREATE = """mutation Create($path:String!, $title:String!, $description:String!, $content:String!,
$isPrivate:Boolean!, $isPublished:Boolean!, $tags:[String]!, $locale:String!, $editor:String!) {
pages { create(path:$path, title:$title, description:$description, content:$content,
isPrivate:$isPrivate, isPublished:$isPublished, tags:$tags, locale:$locale, editor:$editor) {
responseResult { succeeded errorCode slug message } page { id path title } } } }"""
def gql(query, variables=None):
req = urllib.request.Request(BASE.rstrip("/") + "/graphql",
data=json.dumps({"query": query, "variables": variables or {}}).encode(),
headers={"Content-Type": "application/json", "Authorization": "Bearer " + KEY})
return json.loads(urllib.request.urlopen(req, timeout=60).read())
recs = [json.loads(l) for l in open("build/pages_import.jsonl")]
existing = {p["path"] for p in gql('{ pages { list(locale:"ja", limit:10000) { id path } } }')
["data"]["pages"]["list"]}
todo = [r for r in recs if r["path"] not in existing]
print("to create:", len(todo), "skip:", len(recs) - len(todo))
log = open("build/import_log.jsonl", "a")
def create_one(r):
res = gql(CREATE, {"path": r["path"], "title": r["title"], "description": "",
"content": r["content"], "isPrivate": bool(r["isPrivate"]),
"isPublished": True, "tags": list(r["tags"]),
"locale": LOCALE, "editor": "markdown"})
log.write(json.dumps({"path": r["path"], "result": res}, ensure_ascii=False) + "\n")
with concurrent.futures.ThreadPoolExecutor(max_workers=6) as ex:
list(ex.map(create_one, todo))
log.close()
# 最後に必ず1回(並列作成で崩れたツリーを組み直す)
gql("mutation { pages { rebuildTree { responseResult { succeeded } } } }")
pages.create の注意点: isPrivate は必須引数(省略するとエラー)。tags は文字列の配列([] を渡す。JSON文字列 "[]" を渡すと「[]」という名前のタグが作られる)。import_log.jsonl に残る。再実行すれば存在チェックでスキップされ、失敗分だけ作り直せる(冪等)。通常サイズ(1GB 未満)は DB に格納する。assets 行と、実体を持つ assetData 行の2つを作る。hash はファイル名の SHA-1、kind は種類(画像なら image、それ以外は file)で、配信 URL は /<filename> になる。
-- 実体は bytea で。ファイルサイズが大きいときは1ファイル1回に分けて流す
WITH ins AS (
INSERT INTO assets (filename, hash, ext, kind, mime, "fileSize", "folderId", "authorId", "createdAt", "updatedAt")
VALUES ('<fileName>', sha1('<fileName>'), '<ext>', 'file', '<mime>', <bytes>, NULL, 1, now(), now())
RETURNING id
)
INSERT INTO "assetData" (id, data) SELECT id, '\x<hex>'::bytea FROM ins;
assetData → assets の順に消してから入れ直す。bytea の 1 行 1GB 上限)。DISK ストレージを有効にして、「目録だけ DB、実体はファイル」の形にする:-- DISK ストレージ運用: assets 行だけ作り、実体は <WIKI_DATA_DIR> に置く
INSERT INTO assets (filename, ext, kind, mime, "fileSize", "folderId", "authorId", "createdAt", "updatedAt", hash)
VALUES ('large.zip', 'zip', 'file', 'application/zip', 1445277100, NULL, 1, now(), now(), sha1('large.zip'));
DISK ストレージでは、実体ファイルの所有者をコンテナの実行ユーザーに合わせる(合っていないと 500 になる)。設定 API での変更は次のとおり。
curl -s <API_BASE>/graphql -H "Authorization: Bearer <API_KEY>" -H 'Content-Type: application/json' \
-d '{"query":"mutation { site { updateConfig(pageExtensions:\"md, html\", uploadMaxFileSize: 2147483647) { responseResult { succeeded } } } }"}'
uploadMaxFileSize は 32bit 整数なので上限は 2147483647(2GiB − 1)。「5GB」を与えると値が表現できず、管理画面の設定取得が壊れる(実測)。pageExtensions に txt を入れると、.txt の添付ファイルがページ扱いされて 404 になる(実測)。ここが一番の落とし穴。wiki.js の「非公開(isPrivate)」は表示上のラベルで、ゲスト(未ログイン)の読み取りは止まらない。実際に URL を知っていれば本文が読めた。鍵はグループのページルールだけ。
やることは決まっている。
grant が 1 以外だったページ)。path と /path の両方を登録する(照合のしかたの都合で片方だとすり抜ける)。match は EXACT。groups.update の pageRules は全置換なので、既存の許可ルールも必ず含めて渡す。import json, urllib.request, os
BASE, KEY = "<API_BASE>", os.environ["WIKIJS_API_KEY"]
PAGE_DENY = ["read:pages", "write:pages", "manage:pages", "read:comments", "write:comments"]
ASSET_DENY = ["read:assets", "read:pages"]
GUEST_PERMISSIONS = ["read:pages", "read:assets", "read:comments"]
def gql(q, v=None):
req = urllib.request.Request(BASE.rstrip("/") + "/graphql",
data=json.dumps({"query": q, "variables": v or {}}).encode(),
headers={"Content-Type": "application/json", "Authorization": "Bearer " + KEY})
return json.loads(urllib.request.urlopen(req).read())
# 既存ルールを取得(消さないため)
g = gql('{ groups { single(id: 2) { pageRules { id deny match roles path locales } } } }'
)["data"]["groups"]["single"]
rules = [r for r in g["pageRules"] if not r["id"].startswith("mig-")]
private_pages = [p["path"] for p in map(json.loads, open("build/pages_import.jsonl")) if p["isPrivate"]]
private_assets = [a for a in json.load(open("build/assets_scope.json"))] # 非公開ページが参照する添付
for i, p in enumerate(private_pages):
for variant in (p, "/" + p):
rules.append({"id": f"mig-page-{i}", "deny": True, "match": "EXACT",
"roles": PAGE_DENY, "path": variant, "locales": []})
for i, a in enumerate(private_assets):
for variant in (a, "/" + a):
rules.append({"id": f"mig-asset-{i}", "deny": True, "match": "EXACT",
"roles": ASSET_DENY, "path": variant, "locales": []})
mut = """mutation U($rules:[PageRuleInput]!) {
groups { update(id:2, name:"Guests", redirectOnLogin:"/", permissions:%s, pageRules:$rules) {
responseResult { succeeded message } } } }""" % json.dumps(GUEST_PERMISSIONS)
print(gql(mut, {"rules": rules}))
実測では 419 ルール(非公開ページ41件×2バリアント+添付168件×2バリアント+既存ルール)になった。
API キー付きで叩いた結果は検証にならない(権限チェックを素通りする)。必ずキーなしで叩く。
期待値はこう作る: 非公開ページ = 403、公開ページ = 200、添付 = 参照元ページの公開状態に合わせる。
import concurrent.futures, json, urllib.error, urllib.parse, urllib.request
BASE = "<API_BASE>"
jobs = [("pub page", "Knowledge/Open", 200), ("priv page", "Knowledge/Secret", 403)]
def probe(job):
_, path, want = job
try:
with urllib.request.urlopen(urllib.request.Request(
BASE + "/" + urllib.parse.quote(path),
headers={"Range": "bytes=0-0"}), timeout=30) as r:
got = r.status
except urllib.error.HTTPError as e:
got = e.code
ok = (got == want) if want == 403 else (got in (200, 206))
return job, got, ok
bad = 0
with concurrent.futures.ThreadPoolExecutor(max_workers=8) as ex:
for (kind, path, want), got, ok in ex.map(probe, jobs):
if not ok:
bad += 1
print(f"MISMATCH {kind} {path} want={want} got={got}")
print("targets:", len(jobs), "mismatch:", bad)
実測: 724 ターゲット(公開ページ276 / 非公開ページ41 / 公開添付239 / 非公開添付168)で不一致 0。
あわせて確認するもの:
is-invalid-page)」が 0 件sitemap.xml を作る」という自前生成にする。lastmod はページの更新日時を使い、日本語 URL は percent-encode する。sitemap.xml と robots.txt を静的配信する(wiki.js の添付配信は Content-Disposition: attachment が付くため、Search Console が sitemap として受理しない)。補足: サイトの favicon や manifest も wiki.js の既定ファイルを置き換える必要がある(theming.setConfig の injectHead を使う)。これは移行とは別作業なので、必要になったら個別に対応する。
# バックアップ(DB ダンプ + 添付領域)
docker exec <DB_CONTAINER> pg_dump -U <DB_USER> -Fc <DB_NAME> > wiki_db.dump
tar -czf wiki_storage.tar.gz <WIKI_DATA_DIR>
# 復元
docker exec -i <DB_CONTAINER> pg_restore -U <DB_USER> -d <DB_NAME> --clean --if-exists < wiki_db.dump
tar -xzf wiki_storage.tar.gz -C <WIKI_DATA_DIR>
SHA256SUMS を付ける。この記事は、エージェントが順に実行できるように書いてある。ただし全部を自動でやらせると危ない部分があるので、切り分けを示す。
エージェントだけで実行できる部分
report.txt の集計を合格条件にできる。import_log.jsonl を見て失敗分だけ再実行できる。人間の判断・許可が必要な部分
受け入れ条件の書き方(そのまま使える形)
1) export/growi_pages.jsonl の行数 == GROWI のページ数
2) build/report.txt の duplicate paths / illegal paths / empty pages がすべて空
3) import_log.jsonl の succeeded 件数 == 移行対象ページ数
4) Step6 の検証: mismatch == 0(公開 200 / 非公開 403)
5) 管理画面の is-invalid-page == 0
6) 代表ページの目視(表・添付・コードブロック)
7) バックアップ1回 + 復元1回が成功
冪等性の担保
mig-...)の分だけ作り直す=実行のたびに同じ結果になる。失敗時の分岐
| 症状 | エージェントの取るべき行動 |
|---|---|
| 認証エラー(Forbidden) | API キーの権限を確認し、人間に確認を求める。キーを推測・再発行しない |
| 「already exists」 | 既存パスとしてスキップ(冪等なので異常ではない) |
| 一部ページだけ失敗 | import_log.jsonl の失敗分だけ再実行。全体をやり直さない |
| 検証で不一致 | その URL の権限ルールと可視性を確認。本番切替の前に必ず解消 |
| DB の件数が合わない | Step 2 に戻る(変換かダンプの取りこぼし) |
| 症状 | 原因 | 回避策 |
|---|---|---|
| 同じページを何度も作ろうとして失敗が延々と出る | 存在確認の応答キーを single と読み間違えた(正しくは singleByPath) |
正しいキーで確認する(実測で293件が該当) |
| 索引ページから年が1つ抜ける | ページを入れ終える前に索引を作った | 全ページ投入後に索引を作り直す |
| 「作成に失敗」と返るのに作成されている | ツリー再構築処理との衝突 | 失敗時は読み直して更新に切り替え、最後に rebuildTree |
| 更新したらトップページがゲストから見えなくなった | pages.update は省略した項目を既定値で上書きする |
content / isPublished / tags を必ず全部渡す |
| 非公開ページが読めてしまう | isPrivate はラベルであって鍵ではない |
Guests のページルールで拒否し、ゲストで 403 を実測 |
| 1GB のファイルが入らない | bytea の 1 行上限 |
DISK ストレージ運用に切り替える |
.txt の添付が 404 |
pageExtensions に txt が入っている |
md, html にする |
Q. GROWI 以外の Wiki からでも移行できる?
A. できる。Step 1 の書き出しだけ差し替えれば、URL の整理 → リンク変換 → 投入 → 権限 → 検証 の流れは共通だ。
Q. 移行中も元のサイトは使える?
A. 使える。コピー移行なので元は無傷。Step 7 まで本番に影響しない。
Q. 非公開ページは本当にゲストから見えない?
A. ページルールを入れて、ゲストとして叩いて 403 を確認するところまでやって初めて安心できる。これを自動検証に組み込むのがおすすめ。
Q. 1GB を超える添付が出てきたら?
A. DISK ストレージに置く。設定 API の上限(2GiB − 1)を超えるサイズは DB 直書きの運用になる。
Q. 何度もやり直して大丈夫?
A. 大丈夫。ページも添付も「無ければ作る」方式で、権限ルールも毎回作り直す。途中で止まったら、そのまま再実行すれば続きから進む。
数値は 2026-09-30〜10-01 に実測したもの。バージョンが変われば変わる可能性がある。
🤖 このページにはAIエージェント(ノア)による編集・加筆が含まれます。内容の正確性は保証できないため、重要な判断は一次情報でご確認ください。