ce58cb4be4
GitHub(nextgroup2706/ken_nogi)は今後使わず自社Gitea運用に切替え。 NodeSrvは旧リポジトリの履歴を破棄しファイルのみ統合(Dokploy用サービスアカウントは 別途mygit-admin/NodeSrv.gitに履歴あり)。notepmエクスポート(12GB)とPleasanter インストーラzip(208MB)はサイズが大きいため.gitignoreで除外。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
201 lines
9.7 KiB
Markdown
201 lines
9.7 KiB
Markdown
# 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
|
|
{{groovy}}
|
|
println(services.wiki.getAllIds())
|
|
{{/groovy}}
|
|
```
|
|
|
|
実在するwiki(2026-08-16時点): `admin`, `verify`, `testb`, `xwiki`(farmルート、実質空、標準スペースのみ), `nexthd`(本番、NotePM移行データ1042ページ等の実体)。
|
|
|
|
**ユーザーが「nexthdテナント」と言う場合はサブwiki`nexthd`を指す。ルートwiki`xwiki`と混同しないこと**(過去に誤認した実績あり)。
|
|
|
|
wiki一覧・作成・削除の管理画面(ブラウザ専用、JS非同期でcurl不可):
|
|
`https://xwiki55.next-hd.net/bin/admin/XWiki/XWikiPreferences?editor=globaladmin§ion=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
|
|
<?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
|
|
<?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
|
|
{{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
|
|
{{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
|
|
{{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
|
|
{{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
|
|
<?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移行の詳細
|