Notemod-selfhosted ヘルプ（v1.4.6）

Notemod-selfhosted ウェブ用マニュアル（v1.4.6）

Notemod-selfhosted は、本家 Notemod（静的UI / ブラウザのローカルストレージに保存）をベースに、「自分のサーバーに置いて、JSON を単一データソースとして運用する」ことに特化した自己ホスト版です。データベースを必要とせず、ファイル一式をサーバーにアップロードするだけで利用開始できます。

外部サービスに依存せず、Windows PC と iPhone 間のテキスト・画像・ファイルのやり取りを円滑にする目的で開発されています。simplenote.com などのノートサービスの代替にもなり得ます。

v1.4.6 では image_index.json の追加、file_index.json / image_index.json の lock フラグ対応、media_files.php のロック / アンロック UI、ロック中メディアの削除除外、cleanup 時の lock 状態引き継ぎ に加えて、認証まわりの security header / CSRF / rate limit / audit log 強化、setup_auth.php / clipboard_sync.php / media_files.php のトークン露出削減、api/image_api.php の user 解決整理 も行い、運用面とセキュリティ面を広く強化しています。

1. Notemod-selfhosted とは

主な特徴

  • Windows アプリ（ClipboardSync）と iPhone ショートカットによって、クリップボード（テキスト、画像、ファイル）を異なるデバイスで共有できます。
  • GitHub / Gist 非依存で、ノート本体を notemod-data/<USER_NAME>/data.json に集約
  • PHP による同期 (save / load) と API を提供
  • Web UI 認証に対応し、Basic 認証が使えないサーバーでもログイン保護しやすい
  • config/<USER_NAME>/... / notemod-data/<USER_NAME>/... / logs/<USER_NAME>/... のユーザー別構成
  • media_files.php による画像 / ファイル管理
  • bak_settings.php によるバックアップ設定・手動バックアップ・リストア
  • api/image_api.php による保存済み画像の直接表示・サイズ指定
  • logger.php によるアクセスログ記録
  • data.json の任意暗号化保存に対応
  • setup_auth.php で認証用メールアドレスを必須設定可能
  • forgot_password.php / reset_password.php によるパスワードリセット対応
  • config/mail.php による全ユーザー共通メール設定
  • mail() / SMTP の両対応
  • log_settings.php から SMTP 設定の編集と SMTP テスト送信が可能
  • config/<USER_NAME>/config.php による sync save 前バックアップ設定
  • SYNC_PRE_SAVE_BACKUP_ENABLED により、Web UI の sync save 前バックアップの有効 / 無効を切り替え可能
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED により、sync save 前バックアップ直前の古いバックアップ整理を有効 / 無効に可能
  • image_index.json により、現存画像一覧のインデックス管理に対応
  • file_index.json / image_index.json の各要素に lock を持ち、削除除外状態を保持可能
  • media_files.php から、画像 / ファイルごとに ロック / アンロック を切り替え可能
  • ロック中の画像 / ファイルは、個別削除・一括削除・cleanup 系削除から除外可能
  • HTML系画面に共通 security header を付与
  • login.php / forgot_password.php / reset_password.php に rate limit を追加
  • 主要フォームと token reveal / media relay 操作に CSRF 対策を追加
  • logs/system/audit.log に監査ログ（JSON Lines）を保存
  • setup_auth.php で既存 API トークンを平文表示しない方式に改善
  • clipboard_sync.php で API トークンを初期伏字・一時表示・自動再ロック方式に改善
  • media_files.php でブラウザへ API token 実値を直接出さない中継方式に改善
  • api/image_api.php で user / dir_user / username の解決ロジックを整理
  • v1.4.6 では、従来の API 活用や認証・メール運用、バックアップ自動整理に加えて、メディアロックと認証まわりの保護強化を含む管理運用性も広がりました

v1.4.6 の主な追加・改善

  • v1.4.5 の Web UI の sync save 前バックアップ設定化、直前の古いバックアップ自動整理設定 を継承
  • notemod-data/<USER_NAME>/image_index.json を追加
  • 画像アップロード時に image_index.json を差分更新するよう改善
  • 画像削除や purge 後に image_index.json を再生成するよう改善
  • media_files.php が画像一覧構築時に image_index.json を優先して利用するよう改善
  • file_index.json の各要素に lock を追加
  • image_index.json の各要素に lock を追加
  • lock の値は boolean (true / false)
  • 新規追加される画像 / ファイルの lock 初期値は false
  • media_files.php に、各画像 / ファイル行のチェックボックス右側へ ロックアイコン UI を追加
  • ロックアイコンはクリックのたびに ロック / アンロック を切り替え可能
  • ロック UI は既存画面になじむよう、小さめのアイコンボタンとして調整
  • lock=true の画像 / ファイルは削除対象から除外
  • チェックボックスで選択されていても、ロック中メディアは削除されないよう改善
  • api/cleanup_api.php で file_index.json / image_index.json を再生成する際、既存 index の lock 状態を引き継ぐ よう改善
  • これにより、cleanup や purge 後もロック設定が失われにくくなりました
  • auth_common.php を中心に、HTML系画面の共通 security header を整理
  • login.php のログイン成功時に session_regenerate_id(true) を実施
  • login.php / forgot_password.php / reset_password.php に short-time rate limit を追加
  • auth_common.php に監査ログ共通処理を追加し、logs/system/audit.log（JSON Lines）へ保存するよう改善
  • setup_auth.php で EXPECTED_TOKEN / ADMIN_TOKEN の既存値を平文表示しないよう改善
  • clipboard_sync.php で API token を初期伏字表示、ロック解除時だけ 10 秒間一時表示、表示中のみコピー可能に改善
  • clipboard_sync.php の reveal_token POST に CSRF 保護を追加
  • media_files.php でブラウザへ EXPECTED_TOKEN / ADMIN_TOKEN を直接出さない中継方式へ改善
  • media_files.php の download / upload / cleanup / lock 操作に CSRF 保護を追加
  • media_files.php で file.json（JSON Lines）履歴からの復元表示補助として parse_file_history_jsonl() を追加
  • api/image_api.php で user / dir_user / username を使った user 解決ロジックを整理
  • v1.4.3 の append / search / journal API 拡張、v1.4.2 の スナップショット正規化、インポート安定化、セッション設定拡張、XSS 対策、任意暗号化対応 も継続

2. 動作要件

  • PHP 8.1 以上を推奨
  • HTTPS を推奨
  • よく必要になる拡張:
  • json
  • mbstring
  • 画像変換やリサイズを行う場合は gd 系拡張が必要なことがあります
  • SMTP 送信で TLS / SSL を使う場合は OpenSSL 系が使える環境を推奨
  • .htaccess が使える環境を推奨

共有サーバーでは、.htaccess の有効 / 無効、PHP 拡張、メール送信機能の有無、SMTP 通信制限の有無が環境ごとに異なります。事前確認を推奨します。

3. ディレクトリ構成（v1.4.6 標準）

public_html/
├─ index.php
├─ logger.php
├─ notemod_sync.php
├─ setup_auth.php
├─ login.php
├─ logout.php
├─ account.php
├─ forgot_password.php
├─ reset_password.php
├─ auth_common.php
├─ bak_settings.php
├─ log_settings.php
├─ clipboard_sync.php
├─ media_files.php
├─ data_crypto.php
├─ manifest.php
├─ sw-register.js
├─ service-worker.js
├─ sw.php
├─ api/
│  ├─ api.php
│  ├─ read_api.php
│  ├─ image_api.php
│  ├─ cleanup_api.php
│  ├─ append_api.php
│  ├─ search_api.php
│  ├─ journal_api.php
│  └─ .htaccess
├─ config.sample.php
├─ config.sample.ja.php
├─ config.api.sample.php
├─ config.api.sample.ja.php
├─ config/
│  ├─ mail.php
│  └─ <USER_NAME>/
│     ├─ auth.php
│     ├─ config.php
│     ├─ config.api.php
│     └─ password_reset.json
├─ notemod-data/
│  └─ <USER_NAME>/
│     ├─ data.json
│     ├─ note_latest.json
│     ├─ image_latest.json
│     ├─ image_index.json
│     ├─ file_latest.json
│     ├─ file.json
│     ├─ file_index.json
│     ├─ _known_ips.json
│     ├─ images/
│     └─ files/
├─ logs/
│  ├─ <USER_NAME>/
│  └─ system/
│     └─ audit.log
└─ pwa/
   ├─ icon-192.png
   └─ icon-512.png

補足

  • config/ と notemod-data/ は、ユーザー名ディレクトリ配下に保存されます
  • config/mail.php は 全ユーザー共通メール設定 です
  • data_crypto.php は index.php と同じ階層に置く前提です
  • api/ は公開ディレクトリ配下に置きますが、運用時は追加の保護を推奨します

4. 初回セットアップ

4.1 サーバーへ配置

ファイル一式を Web の公開フォルダーへアップロードします。
例: public_html/

4.2 setup_auth.php で初期設定

ブラウザで setup_auth.php にアクセスし、次を設定します。

  • 初期ユーザー
  • パスワード
  • 認証用メールアドレス
  • SECRET（自動で設定されます）
  • EXPECTED_TOKEN
  • ADMIN_TOKEN
  • 必要に応じて暗号化設定
  • 必要に応じてセッション設定
  • 必要に応じて sync save 前バックアップ関連の初期設定

初回作成時には、必要に応じて以下が自動生成されます。

  • config/<USER_NAME>/auth.php
  • config/<USER_NAME>/config.php
  • config/<USER_NAME>/config.api.php
  • notemod-data/<USER_NAME>/data.json

4.3 初回アクセス後に確認したいもの

  • config/<USER_NAME>/... が作成されている
  • notemod-data/<USER_NAME>/... が作成されている
  • logs/<USER_NAME>/ が必要に応じて作成されている
  • セキュリティヘッダが有効な状態で各画面へアクセスできる
  • 認証成功後にセッションが再生成される
  • Web UI にログインできる
  • API トークンが期待通りに保存されている
  • config/<USER_NAME>/auth.php に EMAIL が保存されている
  • config/<USER_NAME>/config.php に
  • SYNC_PRE_SAVE_BACKUP_ENABLED
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED
    が保存されている
  • SESSION_COOKIE_LIFETIME などのセッション設定が意図通りなら確認する
  • SMTP 設定を保存した場合は config/mail.php が作成されていることを確認する
  • logs/system/audit.log が必要に応じて生成されることを確認する
  • 画像やファイルを追加した場合は
  • image_index.json
  • file_index.json
    が生成・更新されることを確認する

5. セキュリティ（重要）

5.1 推奨の順

  1. API ディレクトリに Basic 認証 + Web UI 認証 + API トークン
  2. Basic 認証が使えない場合は Web UI 認証 + API トークン
  3. 可能なら IP 制限
  4. 必要に応じて公開範囲の分離

5.2 保護対象

最低限、次は外部から直接見せない設計を推奨します。

  • config/<USER_NAME>/
  • notemod-data/<USER_NAME>/
  • logs/<USER_NAME>/
  • config/mail.php

5.3 API トークンの使い分け

  • 通常操作:
  • EXPECTED_TOKEN
  • 危険操作:
  • ADMIN_TOKEN

ADMIN_TOKEN を分けておくと、削除系 API のリスクを下げやすくなります。

5.4 画像公開について

api/image_api.php は、現在の実装では token ではなく user と file で保存済み画像を返します。
そのため、次を事前に考えてください。

  • 画像 URL を誰に公開するか
  • user と file の推測しやすさ
  • api/ 全体に Basic 認証をかけるか
  • 外部共有したい画像と非公開画像の運用ルール

5.5 XSS 対策について

v1.4.6 でも、v1.4.2 以降に引き続き、ノートタイトル、カテゴリ名、本文表示、編集モーダル、HTML 挿入まわりのクライアント側処理を見直しています。
ただし、公開運用する場合は、引き続き公開範囲の最小化、強い認証、独自改造部分の見直しをおすすめします。

5.6 認証系の追加保護

v1.4.6 では、Basic 認証や Web UI 認証に加えて、認証まわりの保護を次のように強化しています。

  • HTML系画面に共通 security header を付与
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: SAMEORIGIN
  • Referrer-Policy: same-origin
  • Cache-Control: no-store, no-cache, must-revalidate, max-age=0
  • Pragma: no-cache
  • login.php のログイン成功時に session_regenerate_id(true) を実施
  • login.php / forgot_password.php / reset_password.php に rate limit を追加
  • 主要フォームに CSRF token を導入
  • clipboard_sync.php の token reveal、media_files.php の download / upload / cleanup / lock 操作にも CSRF 保護を導入

5.7 監査ログ

v1.4.6 では監査ログを追加しました。

  • 保存先: logs/system/audit.log
  • 形式: JSON Lines
  • 主な対象:
  • ログイン成功 / 失敗
  • rate limit 発動
  • パスワードリセット申請 / 完了 / 失敗
  • setup_auth.php 更新
  • account.php / log_settings.php / bak_settings.php の主要操作

秘密情報の実値は記録せず、changed フラグや from / to、masked email など必要最小限の差分のみ保存する方針です。

5.8 API トークン露出の抑制

v1.4.6 では API token の扱いも見直しています。

  • setup_auth.php
  • 既存の EXPECTED_TOKEN / ADMIN_TOKEN を平文表示しない
  • 空欄保存時は既存値を維持
  • clipboard_sync.php
  • 初期表示は常に伏字
  • ロック解除時だけサーバーから取得して 10 秒だけ表示
  • 表示中のみコピー可能
  • media_files.php
  • ブラウザへ EXPECTED_TOKEN / ADMIN_TOKEN の実値を直接出さない
  • サーバー側中継で upload / cleanup / lock / download を処理

5.9 認証用メールアドレスと SMTP パスワードについて

  • config/<USER_NAME>/auth.php の EMAIL は認証用メールアドレスです
  • config/mail.php の SMTP_PASSWORD は平文保存です
  • どちらも公開されない配置前提で運用してください

5.10 SMTP と送信元アドレスについて

SMTP を使う場合は、次の整合を確認してください。

  • SMTP_FROM
  • IP_ALERT_FROM
  • SMTP 認証に使うアカウント
  • 送信元ドメインの SPF / DKIM

Gmail などでは、未認証の送信者アドレスを使うと拒否される場合があります。

6. Web UI 認証と管理画面

index.php

通常の Notemod 本体画面です。ノートの閲覧・編集・カテゴリ管理の中心です。

補足（v1.4.6 の同期安全性改善）:

  • notemod_sync.php との通信で 401 / 403 を検出した場合、自動同期を停止 し、再ログインが必要であることを画面上に明示するよう改善
  • セッション失効後は、Load from Server による危険な上書き を防ぐため、条件に応じて自動読み込みや手動読み込みを抑止するよう改善
  • セッション失効後にローカル変更が発生した場合のみ 強い警告を表示するよう調整し、通常時に毎回赤警告が出続ける誤表示を修正
  • 正常に同期成功した後は、警告フラグを解除して通常状態へ戻るよう調整

login.php

Web UI 認証を使う場合のログイン画面です。
v1.3.1 では、後述のカスタム設定メニュー関連ページと UI を統一し、ログイン後の画面遷移で見た目や操作感が揃うように改善されました。
v1.4.6 でも、「パスワードを忘れた場合」 リンクと、パスワードリセット成功時のメッセージ表示に対応しています。
また、ログイン成功時にはセッション再生成を行い、失敗試行には rate limit を適用しています。

account.php

ユーザー名の変更やパスワードの変更が可能です。
また、各種カスタム設定メニューへの入口にもなります。
v1.4.6 でも、account.php からパスワード変更しても auth.php の EMAIL が消えないように改善された状態を継続しています。

clipboard_sync.php

クリップボード連携設定用の画面です。Windows アプリ（ClipboardSync）や iPhone ショートカットのダウンロードリンクを提供し、さらに各種設定を容易にします。API URL を確認・コピーでき、API token は初期伏字表示・一時表示・自動再ロック方式で扱います。

主な機能:

  • ClipboardSync ダウンロードリンク
  • iPhone ショートカット配布リンク
  • API ディレクトリ / api.php / read_api.php / cleanup_api.php URL のコピー
  • EXPECTED_TOKEN / ADMIN_TOKEN の初期伏字表示
  • ロック解除時だけ 10 秒間の一時表示
  • 表示中のみコピー可能
  • reveal_token の POST に CSRF 保護

補足:

  • トークンは現在ログイン中ユーザーの config/<DIR_USER>/config.api.php を参照します
  • 表示時間経過後は自動再ロックされます

media_files.php

画像とファイルの管理画面です。画像とファイルのアップロード、個別削除、全削除が可能です。また、サーバーのアップロード / ダウンロード関連設定を確認できます。v1.4.6 では、API token をブラウザへ直接出さない中継方式へ整理しています。

主な機能:

  • サーバーのファイル設定の確認
  • 画像一覧の表示
  • ファイル一覧の表示
  • ドラッグ＆ドロップアップロード
  • 画像 / ファイルのダウンロード
  • 画像サムネイルクリックによる画像コピー
  • 画像 / ファイルの整理
  • チェックボックス選択削除
  • 全選択 / 全解除
  • 画像ごとのロック / アンロック
  • ファイルごとのロック / アンロック
  • ロック中メディアの削除除外
  • 画像一覧構築時の image_index.json 優先読込
  • ファイル一覧構築時の file_index.json 優先読込
  • download / upload / cleanup / lock 操作への CSRF 保護
  • ブラウザへ API token 実値を直接出さないサーバー側中継方式
  • file.json（JSON Lines）履歴からの復元表示補助

補足:

  • ロックアイコンは、各行のチェックボックス右側に配置されます
  • ロック中 (lock=true) の項目は削除対象から除外されます
  • アンロック中 (lock=false) の項目は従来どおり削除可能です

bak_settings.php

データ（data.json）のバックアップ設定画面です。

主な機能:

  • 同期保存前バックアップを有効（SYNC_PRE_SAVE_BACKUP_ENABLED）
  • 同期保存前に古いバックアップを整理する（SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED）
  • バックアップの有効 / 無効
  • 保持数設定
  • 今すぐバックアップ
  • 古いバックアップ削除
  • バックアップからのリストア

補足:

  • SYNC_PRE_SAVE_BACKUP_ENABLED は、Web UI の sync save で実保存直前バックアップを作るかどうかを制御します
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED は、上記バックアップを作る直前に、古いバックアップ整理を自動実行するかどうかを制御します
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED は、SYNC_PRE_SAVE_BACKUP_ENABLED の下に少しインデントされた子項目として表示されます
  • 古いバックアップ整理の動作は、「最新から n個のバックアップを残す『削除』」 と同じです
  • 古いバックアップ整理の件数判定には CLEANUP_BACKUP_KEEP を使います

log_settings.php

アクセスログの保持・削除設定画面です。IP アクセス通知の設定（メールアドレス）も扱います。
v1.4.6 でも、認証用メールアドレスの反映、SMTP 設定、SMTP テスト送信に対応しています。

主な機能:

  • アクセスログの有効 / 無効
  • アクセスログを Notemod のカテゴリーに保存の有効 / 無効
  • アクセスログの最大行数の設定
  • 初めての IP アクセスからのアクセスの際に通知の有効 / 無効
  • IP アクセス通知のメールアドレスを設定
  • 認証用メールを反映 ボタン
  • SMTP 設定（開閉式 UI）
  • SMTP テスト送信
  • SMTP パスワードの安全な保持
  • 画面に既存値を再表示しない
  • 空欄保存時は現在値を保持

setup_auth.php

Web UI 認証を初期設定する画面です。
Basic 認証が使えない環境でも、Web UI 認証 + API トークン運用をしやすくするための入口になります。
v1.4.6 でも、認証用メールアドレスを必須入力にし、config/<USER_NAME>/auth.php に保存します。
また、初回セットアップ時は未ログインで利用でき、認証設定済み後の変更はログイン済みユーザーのみ可能です。既存の EXPECTED_TOKEN / ADMIN_TOKEN は平文再表示せず、空欄保存時は既存値を維持します。
さらに、新規生成される config.php には

  • SYNC_PRE_SAVE_BACKUP_ENABLED
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED
    が含まれます。

forgot_password.php

パスワードリセット申請画面です。
入力は ユーザー名またはメールアドレス を受け付けます。
結果文言は常に同一にし、存在確認に使われにくいようにしています。さらに、短時間連続申請への rate limit も追加しています。

reset_password.php

メールで受け取ったトークン付き URL から開く、新しいパスワード設定画面です。
トークン有効期限は 30 分で、成功後は login.php?reset=success に戻ります。短時間連続試行には rate limit を適用し、成功時には関連 bucket をクリアします。

7. data.json、保存形、暗号化

7.1 data.json の役割

Notemod の本体データは notemod-data/<USER_NAME>/data.json に保存されます。

代表的な内容:

  • categories
  • notes
  • selectedLanguage
  • hasSelectedLanguage
  • categoryOrder
  • noteOrder

クライアントやインポート経路によっては、これらが文字列化された形で届く場合があります。
そのため v1.4.6 でも、save 前にスナップショットを正規化する仕組みを引き続き利用します。

7.2 v1.4.6 でも引き継がれる正規化処理

notemod_sync.php は、空保存チェック・差分判定・実保存の前に nm_sync_normalize_snapshot() を適用します。

主な補正対象:

  • categories
  • notes
  • categoryOrder
  • noteOrder
  • hasSelectedLanguage
  • selectedLanguage

これにより、たとえば次のような壊れた保存を防ぎやすくします。

"categories": "[{\\"id\\":...}]",
"notes": "[{\\"id\\":...}]"

7.3 暗号化対応

data.json は、引き続き任意で暗号化保存できます。

  • 暗号化方式: AES-256-CBC + HMAC
  • 設定場所: config/<USER_NAME>/config.php
  • 主な設定キー:
  • DATA_ENCRYPTION_ENABLED
  • DATA_ENCRYPTION_KEY

7.4 暗号化切り替え時の挙動

暗号化の ON / OFF を切り替えるときは、次の安全順序で処理されます。

  1. 現在の data.json を読む
  2. 切り替え直前バックアップを 1 つ作成
  3. 新しい保存形式で書き込みを試す
  4. 成功した場合のみ config/<USER_NAME>/config.php の設定を更新
  5. 失敗時は設定を変更しない

7.5 暗号鍵の扱い

  • DATA_ENCRYPTION_KEY は UI で実値を表示しません
  • 鍵が未設定の場合は自動生成できます
  • エクスポートは暗号化有効時でも平文 JSONです

7.6 バックアップファイル名

バックアップは状態に応じて次のような名前になります。

  • 平文バックアップ: data.json.bak-YYYYMMDD-HHMMSS
  • 暗号化バックアップ: data.enc.json.bak-YYYYMMDD-HHMMSS

7.7 Web UI の sync save 前バックアップ

v1.4.6 でも、Web UI の sync save 前バックアップを設定で制御できます。

主な設定キー:

  • SYNC_PRE_SAVE_BACKUP_ENABLED
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED

挙動:

  • SYNC_PRE_SAVE_BACKUP_ENABLED=true の場合、差分があり実保存が必要なときに sync save 前バックアップ を作成します
  • SYNC_PRE_SAVE_BACKUP_ENABLED=false の場合、このバックアップは作成しません
  • SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED=true の場合、sync save 前バックアップを作成する直前に 古いバックアップ整理を行います
  • 古いバックアップ整理は CLEANUP_BACKUP_KEEP を使って件数判定し、bak_settings.php の削除ボタンと同じロジックで動作します
  • 既存環境で SYNC_PRE_SAVE_BACKUP_ENABLED が未設定の場合は、従来互換のため 有効扱い です

7.8 古いバックアップ整理の基準

古いバックアップ整理では、バックアップ一覧を 新しい順（ファイル更新時刻順） に並べます。
そのうえで、先頭から n 件を残し、それ以外を削除します。

  • n は CLEANUP_BACKUP_KEEP
  • n=0 の場合は全削除
  • 平文バックアップと暗号化バックアップをまとめて判定

8. 補助データファイル

ノート系

  • note_latest.json
  • 最新ノート 1 件のメタ情報

画像系

  • image_latest.json
  • 最新画像 1 件のメタ情報
  • image_index.json
  • 現存画像一覧。media_files.php 表示用
  • 各要素に lock を保持
  • images/
  • 画像保存先

ファイル系

  • file_latest.json
  • 最新ファイル 1 件のメタ情報
  • file.json
  • ファイル履歴ログ（JSON Lines）
  • file_index.json
  • 現存ファイル一覧。media_files.php 表示用
  • 各要素に lock を保持
  • files/
  • ファイル保存先

ログ / 管理系

  • _known_ips.json
  • 既知の IP を保持し、初回アクセス通知に利用
  • password_reset.json
  • パスワードリセットトークン情報
  • 保存場所: config/<USER_NAME>/password_reset.json
  • logs/system/audit.log
  • 監査ログ
  • JSON Lines 形式で各種認証・設定操作を記録

補足

v1.4.6 では、画像側にも image_index.json が追加されました。
これにより、画像一覧もファイル一覧と同様にインデックスベースで管理しやすくなりました。

password_reset.json の主な内容は次のとおりです。

  • token_hash または token_hash 相当の情報
  • created_at
  • expires_at
  • used

成功したリセット後は used=true に更新されます。

9. API 全体の考え方

Notemod-selfhosted では、役割ごとに API が分かれています。

  • api.php
  • 追加する API
  • テキスト追加、画像アップロード、ファイルアップロード
  • read_api.php
  • 読む API
  • カテゴリ一覧、ノート一覧、最新ノート、最新画像、最新ファイル、最新クリップ種別など
  • image_api.php
  • 画像を直接配信する API
  • 保存済み画像の表示、media_files.php からの画像コピー補助、画像 URL を使った外部連携
  • user / dir_user / username を使ったユーザー解決
  • cleanup_api.php
  • 整理・削除する API
  • ノート削除、メディア整理、バックアップ削除、ログ削除、バックアップ作成、メディア lock 更新
  • append_api.php
  • 既存ノートへ追記する API
  • 明示指定追記、ラベル付き追記、別ノート本文の差し込み、dry_run
  • search_api.php
  • カテゴリ名 / ノートタイトル / 本文を検索する API
  • note_id 取得、append 先候補の探索、横断検索
  • journal_api.php
  • 日付・月・週・固定ノートへ自動または半自動で追記する API
  • 日記、日報、ログ、ショートカット記録向け

認証は通常 config/<USER_NAME>/config.api.php を使います。

  • api.php / read_api.php / append_api.php / search_api.php / journal_api.php
  • EXPECTED_TOKEN
  • cleanup_api.php
  • ADMIN_TOKEN（未設定時は EXPECTED_TOKEN を使う構成でも可）

10. api.php マニュアル

10-1. 概要

api.php は、Notemod にデータを追加するための API です。

対応する type:

  • text
  • image
  • file

10-2. 受け付け形式

  • GET
  • POST（application/x-www-form-urlencoded / multipart/form-data）
  • POST（application/json）

画像とファイルは multipart/form-data を推奨します。

10-3. 共通パラメータ

パラメータ必須例説明
token必須your_tokenEXPECTED_TOKEN と一致する必要があります
type任意texttext / image / file。省略時は text
pretty任意11 または true で整形 JSON
user任意DIR_USER保存先ディレクトリユーザー

10-4. テキスト追加 (type=text)

追加パラメータ:

パラメータ必須例説明
text必須hello本文
title任意Memo省略時は現在時刻
category任意INBOX省略時は INBOX

仕様:

  • 指定カテゴリが無ければ自動作成
  • 改行は Notemod 互換の HTML 形式へ変換して保存
  • 成功時に note_latest.json を更新
  • 暗号化有効時でも、現在の保存形式に従って保存

10-5. 画像アップロード (type=image)

追加パラメータ:

パラメータ必須例説明
image推奨multipart file画像ファイル

仕様:

  • $_FILES['image'] を優先
  • image 名でなくても、最初のアップロードファイルを利用可能
  • 保存先は notemod-data/<USER_NAME>/images/
  • image_latest.json を更新
  • image_index.json を管理
  • image_index.json の各要素に lock を保持
  • WebP はサーバー側で PNG に変換される場合があります

10-6. ファイルアップロード (type=file)

追加パラメータ:

パラメータ必須例説明
file推奨multipart file一般ファイル

仕様:

  • $_FILES['file'] を優先
  • file 名でなくても、最初のアップロードファイルを利用可能
  • 保存先は notemod-data/<USER_NAME>/files/
  • file_latest.json を更新
  • file.json に履歴を追加
  • file_index.json を管理
  • original_name を保持
  • file_index.json の各要素に lock を保持

18. よくある使い方

media_files.php でメディアをロックする

  1. media_files.php の画像一覧またはファイル一覧を開く
  2. 各行のチェックボックス右側にあるロックアイコンをクリックする
  3. ロック中になった項目は削除対象から除外される
  4. 再度クリックするとアンロックされ、通常どおり削除可能になる

19. トラブルシューティング

ロックしたはずの画像 / ファイルが削除される

考えられる原因:

  • image_index.json / file_index.json に lock が保存されていない
  • media_files.php の lock 更新処理が正常に反映されていない
  • image_index.json / file_index.json の再生成時に lock 引き継ぎが崩れている
  • 画面が古いキャッシュを表示している
  • cleanup_api.php 側で lock 判定前に削除処理へ入っている
  • index 再生成時に lock 引き継ぎが行われていない

確認ポイント:

  • 対象メディアの index 要素に lock=true が保存されているか
  • media_files.php からロック切替後、再読込してもロック状態が維持されるか
  • cleanup 実行後も lock 状態が保持されているか
  • dry_run=1 / dry_run=2 で削除対象一覧に含まれていないか確認する

clipboard_sync.php でトークンが表示されない / すぐ消える

考えられる原因:

  • まだロック解除していない
  • 10 秒の表示時間が経過して自動再ロックされた
  • reveal_token の CSRF token が不足している
  • config/<USER_NAME>/config.api.php に token が保存されていない

確認ポイント:

  • 初期表示が伏字になっているか
  • ロック解除後に 10 秒間だけ表示されるか
  • ロック中はコピーできないか
  • reveal_token が 403 / Invalid CSRF token になっていないか

長時間放置後に同期まわりの警告が出る

考えられる原因:

  • Web UI のログインセッションが失効している
  • セッション失効後にローカルで編集を続けた
  • サーバー側同期が停止している

v1.4.6 では、セッション失効後の危険な自動同期やサーバー読み込みを抑止するため、条件に応じて警告を表示します。

確認ポイント:

  • 再ログインが必要になっていないか
  • Load from Server が安全のために抑止されていないか
  • 警告が出ている間に、失効後のローカル変更が残っていないか
  • 正常に同期成功した後、警告が消えるか

補足:

  • 通常時は赤警告が常時表示されない想定です
  • 強い警告は、主に セッション失効後にローカル変更が発生した場合 に表示されます

20. 運用メモ

  • 秘密情報を含むファイルは Git にコミットしないでください
  • 暗号化有効時でも、エクスポートは平文 JSON です
  • 旧バージョンから移行する場合は、まずユーザー別ディレクトリ構成へ正しく配置してから運用してください
  • 暗号化切り替え前には、バックアップが正常に作れる状態か必ず確認してください
  • sync save 前バックアップを使う場合は、SYNC_PRE_SAVE_BACKUP_ENABLED と SYNC_PRE_SAVE_BACKUP_PRUNE_ENABLED、CLEANUP_BACKUP_KEEP の関係を理解した上で運用してください
  • 本番運用では、Web UI 認証だけに頼らず、可能なら Basic 認証も併用してください
  • SMTP を使う場合は、config/mail.php を安全に保護してください
  • v1.4.6 のメディア lock 機能を使う場合は、削除前に lock 状態を見直す運用をおすすめします
  • clipboard_sync.php では token を一時表示方式にしているため、通常運用では token 実値を画面へ出しっぱなしにしない運用が可能です
  • media_files.php は token 非露出中継方式ですが、追加改造時も同じ方針を維持することをおすすめします
  • logs/system/audit.log は、必要に応じてローテーションや保守運用を検討してください
Language
PAGE TOP