ken_nogi/NodeSrv/apps/xwiki/docs/xwiki-doc-upload-scheme.md

XWikiドキュメント投入スキーム(Claude向けリファレンス)

対象: https://xwiki55.next-hd.net。REST APIでページ作成・更新・削除・多言語翻訳・拡張インストール・wiki設定変更を行う手順一式。

0. 基本情報

• Base URL: https://xwiki55.next-hd.net
• 認証: Basic認証。apps/xwiki/.env(gitignore対象)に格納
  • XWIKI_BASE_URL / XWIKI_ADMIN_USER / XWIKI_ADMIN_PASSWORD / XWIKI_ADMIN_EMAIL
  • curl例: curl -u "xwiki-admin:PASSWORD" ... ※パスワードに#と$を含むため、bashダブルクォート内では$を\$でエスケープすること
• XWikiバージョン: 17.10.4 (Tomcat 10.1.53 / PostgreSQL)
• インフラ: Node B (Lightsail, Dokploy Remote Server方式)。docker-compose: apps/xwiki/docker-compose.yml

1. マルチwiki(テナント)構成

重要: GET /rest/wikis は全wikiを返さない(原因未特定。nexthdが漏れた実績あり)。真の一覧確認は必ずGroovy経由で行う。

{{groovy}}
println(services.wiki.getAllIds())
{{/groovy}}

実在するwiki(2026-08-16時点): admin, verify, testb, xwiki(farmルート、実質空、標準スペースのみ), nexthd(本番、NotePM移行データ1042ページ等の実体)。

ユーザーが「nexthdテナント」と言う場合はサブwikinexthdを指す。ルートwikixwikiと混同しないこと(過去に誤認した実績あり)。

wiki一覧・作成・削除の管理画面(ブラウザ専用、JS非同期でcurl不可): https://xwiki55.next-hd.net/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=wikis.descriptor

2. URL構造

• ブラウザ表示URL: https://xwiki55.next-hd.net/wiki/{wikiId}/view/{Space}/{Space2}/.../{Page}
  • PageがWebHomeなら省略可(末尾スラッシュのみでOK)
  • 日本語スペース名はURLエンコード必須
• REST API: https://xwiki55.next-hd.net/rest/wikis/{wikiId}/spaces/{Space1}/spaces/{Space2}/.../pages/{Page}
  • ネストスペースはspaces/X/spaces/Y/...で連結(XWikiのネストページ機構)
  • 正確なブラウザURLはページ取得結果のxwikiRelativeUrlフィールドで確認するのが確実(/wiki/admin/view/...)

3. ページCRUD(REST API)

3.1 作成・更新(PUT)

PUT /rest/wikis/{wikiId}/spaces/{Space1}/spaces/{Space2}/pages/{Page}
Content-Type: application/xml; charset=utf-8
Authorization: Basic ...

body:

<?xml version="1.0" encoding="UTF-8"?>
<page xmlns="http://www.xwiki.org">
  <title>ページタイトル</title>
  <syntax>markdown/1.2</syntax>
  <content>本文(&, <, > はXMLエスケープ必須)</content>
</page>

• 新規作成: 201。更新: 202。
• <syntax>はmarkdown/1.2が全wiki(admin/xwiki/nexthd)で使用可能確認済み(Markdown Syntax拡張導入済み)。xwiki/2.1(標準構文、マクロ{{...}}使用可)も可。
• 子ページ一覧を出すには本文に {{children/}} を書く(非同期xtreeで描画、curlでは中身取得不可、ブラウザでは正常表示)。

3.2 取得(GET)

GET /rest/wikis/{wikiId}/spaces/.../pages/{Page}
Accept: application/json

レスポンスJSONの主要フィールド: title, syntax, content, xwikiRelativeUrl, translations.translations[].language(多言語一覧), parent, created, modified。

3.3 削除(DELETE)

DELETE /rest/wikis/{wikiId}/spaces/.../pages/{Page}

成功: 204。

3.4 一括投入パターン(Node.jsスクリプト)

複数ページを一括投入する場合、fetchで1ページずつPUTするNode.jsスクリプトを書くのが確実(実績: 24ページ一括投入)。要点:

• ファイルはfs.readFileSync(path, "utf8")でそのまま読み、XMLエスケープしてcontentに埋め込む
• スペース配列(["システム構築","org-master-sync"]のような配列)からURL組み立てる関数を用意し、encodeURIComponentを各セグメントに適用
• 認証ヘッダーは"Basic " + Buffer.from("user:pass").toString("base64")

4. 多言語翻訳(ロケール別ページ)

やってはいけないこと: 日本語訳を追加する際、本体(既定ロケール、通常は英語)ページを日本語で上書きしない。ロケール別サブリソースとして追加する。

PUT /rest/wikis/{wikiId}/spaces/.../pages/{Page}/translations/{locale}

body:

<?xml version="1.0" encoding="UTF-8"?>
<page xmlns="http://www.xwiki.org">
  <title>ページタイトル</title>
  <syntax>plain/1.0</syntax>
  <language>ja</language>
  <content>日本語訳本文</content>
</page>

翻訳有無・言語一覧の確認: 通常のGET結果のtranslations.translations[].language配列(例: ["en","de","ko","pt_BR","en_GB","fr","pt","ru","ja"])。個別ロケール取得はGET .../pages/{Page}/translations/{locale}(存在しなければ404)。

5. Groovyスクリプト実行(REST APIで不可能な操作の回避策)

REST APIで扱えない操作(拡張インストール、クロスwikiアクセス、wiki一覧取得等)はGroovyページを作って実行する。

手順:

1. 任意のテンポラリスペースにページ作成(syntax=xwiki/2.1、本文に{{groovy}}...{{/groovy}})
2. GET /wiki/{wikiId}/view/{Space}/{Page}(ブラウザ表示URL、curlで可)にアクセスすると実行される。結果はid="xwikicontent"のdiv内に出力される
3. 実行後は必ずDELETEでテストページを消す(汚さない)

実行にはプログラミング権限(xwiki-adminなら通常あり)が必要。

5.1 クロスwikiドキュメントアクセス

{{groovy}}
def doc = xwiki.getDocument("nexthd:XWiki.XWikiPreferences")
def obj = doc.getObject("XWiki.XWikiPreferences")
println(obj.getValue("leftPanels"))
{{/groovy}}

注意: サブwiki(nexthd等)へのREST直接アクセスはXWikiPreferencesのobjects系エンドポイントで401になった実績あり(原因未特定)。通常ページのGET/PUTは通ることもある。ダメならメインwiki(xwiki)上のGroovy経由でクロスwikiアクセスする。

5.2 拡張(Extension)インストール

{{groovy}}
def job = services.extension.install("org.xwiki.contrib:application-favorites", "1.4.4", "wiki:admin")
println("state=" + job.getStatus().getState())
{{/groovy}}

• シグネチャはinstall(String id, String version, String namespace)の3引数版。namespaceは"wiki:{wikiId}"形式
• 非同期実行。job.join()は過去にハングした実績あり(construction-log参照)。joinせず、別リクエストで完了確認する:

{{groovy}}
def installed = services.extension.getInstalledExtension("org.xwiki.contrib:application-favorites", "wiki:admin")
println(installed != null ? "INSTALLED " + installed.id.version : "NOT YET")
{{/groovy}}

• 拡張の正式IDが不明な場合、既にインストール済みの別wikiで検索:

{{groovy}}
services.extension.installedExtensions.findAll { it.id.id.toLowerCase().contains("favorite") }.each {
  println(it.id.id + " " + it.id.version + " " + it.namespaces)
}
{{/groovy}}

6. XWikiPreferencesオブジェクト(wiki単位設定、パネル構成等)

GET/PUT /rest/wikis/{wikiId}/spaces/XWiki/pages/XWikiPreferences/objects/XWiki.XWikiPreferences/0

個別プロパティのみ更新する場合(推奨、他プロパティへの影響を避けられる):

PUT /rest/wikis/{wikiId}/spaces/XWiki/pages/XWikiPreferences/objects/XWiki.XWikiPreferences/0/properties/{propertyName}

body:

<?xml version="1.0" encoding="UTF-8"?>
<property xmlns="http://www.xwiki.org">
  <value>プロパティ値</value>
</property>

成功: 202。

パネル関連プロパティ: leftPanels, rightPanels(カンマ区切りページ参照、例Panels.Search,Panels.Navigation), showLeftPanels, showRightPanels(0/1), leftPanelsWidth, rightPanelsWidth(Large/Medium等)。

7. 既知のハマりどころ

• REST /rest/wikisが全wiki一覧を返さない → Groovy services.wiki.getAllIds()で確認
• REST objects系エンドポイントがサブwiki直叩きで401になることがある → メインwiki経由Groovyで回避
• Markdown内リンク[text](url)で丸括弧()を含むURLはリンク崩れする(encodeURIComponentは()をエンコードしない仕様のため。詳細はapps/xwiki/docs/2026-08-12-construction-log.md参照)
• Windows/git-bash環境で/tmp直下は書き込み不可な場合あり。一時ファイルはスクラッチパスに置く
• python3が使えない環境がある。JSON整形・抽出はnode -eで代替する
• Extension Manager job.join()はハングすることがある(構築ログに実例あり)。非同期キック+ポーリングで回避
• xwiki.propertiesは非永続領域(xwiki_dataボリューム対象外)。恒久設定変更はdocker-compose.ymlのvolumeマウント追加で対応(詳細: construction-log参照)

8. 参考: 過去の投入実績

• admin wiki「システム構築」配下に24ページ投入(org-master-sync/XWiki/app-portal/allowlist-admin/lightsail-cli/keycloak-monitor/lineworks-board-sync/lineworks-cxtalk-sync/mlmanagerの設計書・実装計画・READMEを集約)。投入スクリプトはNode.js one-shot(リポジトリ非保存、都度3節のパターンで再構築)
• admin wikiにFavorites拡張(org.xwiki.contrib:application-favorites v1.4.4)導入、パネル構成をnexthd相当に複製済み

9. 関連ドキュメント

• apps/xwiki/docs/2026-08-12-construction-log.md: OIDC SSO・NotePM移行・Docker Swarm障害対応等の詳細構築ログ
• docs/XWiki移行_検討ログ.md: 移行検討段階の記録(Wiki製品比較、コスト試算等)
• project_dokploy_multiserver_plan(Claude memory): Dokploy Remote Servers移行の詳細