siyuan-note/siyuan

概要

サーバーでSiYuanを提供する最も簡単な方法は、Dockerを使用してデプロイすることです。

• イメージ名 b3log/siyuan
• イメージURL

ファイル構造

全体のプログラムは /opt/siyuan/ にあり、基本的にはElectronインストールパッケージのresourcesフォルダーの構造です：

• appearance: アイコン、テーマ、言語
• guide: ユーザーガイドドキュメント
• stage: インターフェースと静的リソース
• kernel: カーネルプログラム

エントリポイント

エントリポイントはDockerイメージのビルド時に設定されます：ENTRYPOINT ["/opt/siyuan/entrypoint.sh"]。このスクリプトを使用すると、コンテナ内で実行されるユーザーの PUID と PGID を変更できます。これは、ホストからディレクトリをマウントする際の権限の問題を解決するために特に重要です。PUID（ユーザーID）と PGID（グループID）は環境変数として渡すことができ、ホストマウントディレクトリにアクセスする際に正しい権限を確保するのが容易になります。

docker run b3log/siyuan を使用してコンテナを実行する場合、次のパラメータを使用します：

• --workspace: ワークスペースフォルダーのパスを指定し、ホスト上で -v を使用してコンテナにマウントします
• --accessAuthCode: ロック画面パスワードを指定します

注意: v3.7.0 以降、serve サブコマンドを明示的に渡す必要があります（例: docker run b3log/siyuan serve --workspace=...）。すべてのサーブ用オプションは docker run --rm b3log/siyuan serve --help で確認できます。

詳細なパラメータは --help を参照してください。以下は新しい環境変数を使用した起動コマンドの例です：

先に AuthCode に自分の強力なパスワードを設定してください（Bash では export AuthCode='自分の強力なパスワード' を使用し、Compose では同じディレクトリの .env ファイルからも読み込めます）。未設定または空の場合、例はエラーで停止します。

docker run -d \
  -v workspace_dir_host:workspace_dir_container \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  -e SIYUAN_LANG=ja \
  b3log/siyuan \
  serve \
  --workspace=workspace_dir_container \
  --accessAuthCode="${AuthCode:?Set AuthCode}"

• PUID: カスタムユーザーID（オプション、指定しない場合はデフォルトで 1000）
• PGID: カスタムグループID（オプション、指定しない場合はデフォルトで 1000）
• workspace_dir_host: ホスト上のワークスペースフォルダーのパス
• workspace_dir_container: コンテナ内のワークスペースフォルダーのパス、--workspace で指定されたものと同じ
  • あるいは、SIYUAN_WORKSPACE_PATH 環境変数を使用してパスを設定することもできます。両方が設定されている場合は、コマンドラインの値が優先されます
• accessAuthCode: ロック画面パスワード（必ず変更してください、そうしないと誰でもデータにアクセスできます）
  • また、SIYUAN_ACCESS_AUTH_CODE 環境変数を設定することでロック画面パスワードを指定することもできます。両方が設定されている場合、コマンドラインの値が優先されます
  • 環境変数 SIYUAN_ACCESS_AUTH_CODE_BYPASS=true を設定することで、ロック画面パスワードを無効にすることができます
• OIDC はロック画面パスワードの代わりに Docker アクセス認証として利用できます。SIYUAN_OIDC_ENABLED=true、SIYUAN_OIDC_PROVIDER（custom、google、microsoft、github のいずれか）、SIYUAN_OIDC_CLIENT_ID、および以下のプロバイダー固有の値を設定してください。GitHub は OAuth 2.0 ユーザー API アダプターを使用し、その他のプロバイダーは OpenID Connect ディスカバリーと ID Token 検証を使用します。ロック画面パスワードが利用できない状態で無効な構成を有効にすると、Docker の起動が中断されます
  • SIYUAN_OIDC_ISSUER_URL：custom および microsoft プロバイダーに必要な Issuer URL。Microsoft は https://login.microsoftonline.com/<tenant-id>/v2.0 のようなテナント固有の issuer を使用する必要があります
  • SIYUAN_OIDC_CLIENT_SECRET：OpenID Connect プロバイダー向けの任意のクライアントシークレット。GitHub OAuth アダプターでは必須です。すべての認可コードフローで PKCE を使用します
  • SIYUAN_OIDC_SCOPES：カンマまたはスペース区切りのスコープ。openid は常に含まれます
  • SIYUAN_OIDC_REDIRECT_URL：/api/system/oidc/callback で終わる公開 HTTPS コールバック URL。リモートブラウザーアクセスに必須です
  • SIYUAN_OIDC_ALLOW_ALL：プロバイダーで認証されたすべての ID に SiYuan 管理者アクセスを明示的に付与します
  • SIYUAN_OIDC_CLAIM_RULES：allow-all が無効な場合に使用するクレームルールの JSON 配列。例：[{"claim":"email","operator":"equals","values":["[email protected]"]},{"claim":"email_verified","operator":"equals","values":["true"]}]。ルール内の値は OR、ルール間は AND で評価されます
  • ネイティブモバイルアプリは固定のコールバック URI siyuan:/oidc-callback を使用します。記載どおりに登録してください。モバイル構成の検証は保存前にこのコールバックを使用します。カスタムプロバイダー、Microsoft、GitHub は、アプリ登録がこのコールバック URI を受け入れる場合にのみ使用できます。Google は Android クライアントタイプでこのプライベート URI を受け付けないため、Google ログインはブラウザーおよびデスクトップフローに限定されます
• SIYUAN_LANG：インターフェース言語（オプション、Docker で未設定の場合はデフォルト en）。BCP 47 タグ（zh-CN/zh-TW/en/ja/pt-BR など）を受け付けます。従来のアンダースコア形式（zh_CN/en_US など）も互換性のため受け付けます。設定で選択した言語を再起動後も維持したい場合は、デプロイ時にこの変数を省略してください。設定した場合は起動のたびに適用され、保存済みの言語設定を上書きします
  • あるいは --lang コマンドライン引数でも設定できます。両方が設定されている場合、コマンドラインの値が優先されます

簡略化するために、ホストとコンテナでワークスペースフォルダーのパスを一致させることをお勧めします。たとえば、workspace_dir_host と workspace_dir_container の両方を /siyuan/workspace に設定します。対応する起動コマンドは次のようになります：

先に AuthCode に自分の強力なパスワードを設定してください（Bash では export AuthCode='自分の強力なパスワード' を使用し、Compose では同じディレクトリの .env ファイルからも読み込めます）。未設定または空の場合、例はエラーで停止します。

docker run -d \
  -v /siyuan/workspace:/siyuan/workspace \
  -p 6806:6806 \
  -e PUID=1001 -e PGID=1002 \
  -e SIYUAN_LANG=ja \
  b3log/siyuan \
  serve \
  --workspace=/siyuan/workspace/ \
  --accessAuthCode="${AuthCode:?Set AuthCode}"

Docker Compose

Docker Composeを使用してSiYuanを実行するユーザー向けに、環境変数 PUID と PGID を使用してユーザーとグループのIDをカスタマイズできます。以下はDocker Composeの設定例です：

先に AuthCode に自分の強力なパスワードを設定してください（Bash では export AuthCode='自分の強力なパスワード' を使用し、Compose では同じディレクトリの .env ファイルからも読み込めます）。未設定または空の場合、例はエラーで停止します。

version: "3.9"
services:
  main:
    image: b3log/siyuan
    command: ['serve', '--workspace=/siyuan/workspace/', '--accessAuthCode=${AuthCode:?Set AuthCode}']
    ports:
      - 6806:6806
    volumes:
      - /siyuan/workspace:/siyuan/workspace
    restart: unless-stopped
    environment:
      - TZ=${YOUR_TIME_ZONE}    # タイムゾーン識別子のリストは https://en.wikipedia.org/wiki/List_of_tz_database_time_zones を参照してください
      - PUID=${YOUR_USER_PUID}  # カスタムユーザーID
      - PGID=${YOUR_USER_PGID}  # カスタムグループID
      - SIYUAN_LANG=ja       # インターフェース言語（このドキュメントに合わせる）

この設定では：

• PUID と PGID は動的に設定され、コンテナに渡されます
• これらの変数が提供されていない場合、デフォルトの 1000 が使用されます

環境で PUID と PGID を指定することで、composeファイルで user ディレクティブ（user: '1000:1000'）を明示的に設定する必要がなくなります。コンテナは起動時にこれらの環境変数に基づいてユーザーとグループを動的に調整します。

ユーザー権限

イメージ内で、entrypoint.sh スクリプトは指定された PUID と PGID で siyuan ユーザーとグループを作成することを保証します。したがって、ホストがワークスペースフォルダーを作成する際には、フォルダーのユーザーとグループの所有権を設定し、使用する予定の PUID と PGID に一致させることに注意してください。たとえば：

chown -R 1001:1002 /siyuan/workspace

カスタムの PUID と PGID 値を使用する場合、エントリポイントスクリプトはコンテナ内で正しいユーザーとグループを作成し、マウントされたボリュームの所有権を適切に調整します。docker run または docker-compose で -u を手動で渡す必要はありません。環境変数がカスタマイズを処理します。

隠しポート

NGINXリバースプロキシを使用してポート6806を隠します。注意点：

• WebSocketリバースプロキシ /ws を設定します
• 通常のリクエストと /ws の両方で、ポートを含む元の Host ヘッダーを保持してください。NGINX の両方のプロキシ設定に proxy_set_header Host $http_host; を指定します。$host を使用すると標準以外のポート（例：8443）が失われ、Origin の検証に失敗する場合があります。その結果、ログイン後にロゴ画面で再読み込みを繰り返す、API が 401 を返す、WebSocket 接続に失敗するなどの問題が発生します

注意

• マウントボリュームの正確性を確認してください。そうしないと、コンテナが削除された後にデータが失われます
• URLリライトを使用してリダイレクトしないでください。認証に問題が発生する可能性があるため、リバースプロキシの設定をお勧めします
• 権限の問題が発生した場合、PUID と PGID 環境変数がホストシステム上のマウントされたディレクトリの所有権と一致していることを確認してください

制限

• デスクトップおよびモバイルアプリケーションの接続はサポートされておらず、ブラウザでの使用のみサポートされています
• PDF、HTML、Word形式へのエクスポートはサポートされていません
• Markdownファイルのインポートはサポートされていません

HelmForge SiYuan チャート は HelmForge コミュニティが保守しており、公式の b3log/siyuan イメージを使用します。SiYuan 公式のチャートではありません。チャートに関する問題は HelmForge に報告してください。

Helm、kubectl、およびデフォルトの StorageClass で 10Gi の ReadWriteOnce ボリュームを動的に確保できる Kubernetes クラスターを用意して、次を実行します：

helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install siyuan helmforge/siyuan --namespace siyuan --create-namespace --wait
kubectl -n siyuan get secret siyuan-siyuan-auth -o go-template='{{index .data "access-code" | base64decode}}{{"\n"}}'
kubectl -n siyuan port-forward service/siyuan-siyuan 6806:6806

http://localhost:6806 を開き、生成されたロック画面パスワードを入力します。このパスワードは安全に保管してください。API トークンとは異なる認証情報です。上記のリソース名は、チャートのデフォルト設定とリリース名 siyuan を前提としています。

リモートアクセスには、専用の HTTPS ホスト名と、/ws の WebSocket 接続を中継できる Ingress コントローラーを使用し、URL の書き換えは行わないでください。ingress を設定し、networkPolicy.ingressFrom でコントローラーの名前空間からの通信を許可します。デフォルトのポリシーでは、同じ名前空間からの受信と DNS への送信のみが許可されます。クラウド同期などの外部サービスには、明示的な送信ルールが必要です。TLS、既存の Secret、ストレージの設定は、チャートガイドと本番環境の設定例を参照してください。

• ワークスペースに書き込むインスタンスは 1 つだけ： レプリカ数を増やしたり、同じワークスペースを別の実行中インスタンスにマウントしたりしないでください。ReadWriteMany ストレージでも同様です。チャートは Recreate を使用し、古いインスタンスの停止後に新しいインスタンスを起動するため、アップグレード中はサービスが停止します。
• 永続化： ワークスペース全体を /siyuan/workspace にマウントします。チャートが作成した PVC はアンインストール時にデフォルトで保持されますが、名前空間や PVC を削除するとデータが失われる可能性があります。保持または復元した PVC は persistence.existingClaim で再利用します。
• バックアップとアップグレード： 書き込みインスタンスを正常に停止してからワークスペース全体をバックアップするか、アプリケーションの整合性を保証するバックアップ手順を使用してください。使用中の SQLite インデックスをコピーするだけでは不十分です。認証用 Secret、暗号鍵、暗号化ノートブックの復旧パスワードを安全に保管し、別の PVC への復元をテストしてください。アップグレード前にバックアップを取得し、ストレージ形式の変更を確認してください。Helm のロールバックではデータの移行は元に戻りません。

Docker ホスティングの制限も適用されます。ブラウザーでのみ利用でき、デスクトップおよびモバイルアプリからの接続、PDF・HTML・Word へのエクスポート、Markdown ファイルのインポートはサポートされません。

注意：最初にターミナルで chown -R 1000:1000 /mnt/user/appdata/siyuan を実行します

テンプレートの参考：

Web UI: 6806
Container Port: 6806
Container Path: /siyuan/workspace
Host path: /mnt/user/appdata/siyuan
PUID: 1000
PGID: 1000
SIYUAN_LANG: ja
Publish parameters: serve --accessAuthCode=******（ロック画面パスワード）

注意：まず TrueNAS Shell で以下のコマンドを実行してください。Pool_1/Apps_Data/siyuan をアプリ用のデータセットパスに合わせて更新してください。

zfs create Pool_1/Apps_Data/siyuan
chown -R 1001:1002 /mnt/Pool_1/Apps_Data/siyuan
chmod 755 /mnt/Pool_1/Apps_Data/siyuan

Apps - DiscoverApps - More Options（右上、Custom App を除く）- YAML でインストール に移動してください

テンプレート例：

デプロイ前に、以下の SIYUAN_ACCESS_AUTH_CODE= の後に自分の強力なパスワードを入力してください。空のままにしないでください。

services:
  siyuan:
    image: b3log/siyuan
    container_name: siyuan
    command: ['serve', '--workspace=/siyuan/workspace/']
    ports:
      - 6806:6806
    volumes:
      - /mnt/Pool_1/Apps_Data/siyuan:/siyuan/workspace  # Adjust to your dataset path 
    restart: unless-stopped
    environment:
      - SIYUAN_ACCESS_AUTH_CODE=
      - TZ=Asia/Tokyo  # 必要に応じてタイムゾーンに置き換えてください
      - PUID=1001
      - PGID=1002
      - SIYUAN_LANG=ja  # インターフェース言語（このドキュメントに合わせる）