TOD-K (Terminal for Official Diploma Works – Kiosk)

学生が卒業制作動画を提出するための Web ベースのアップロードシステムです。TUSプロトコル（Tus Resumable Upload Protocol）を使用し、大容量の動画ファイルを安全かつ確実にアップロードできます。

特徴

• TUSプロトコル対応: 断続的なアップロードに対応し、ネットワーク障害時も再開可能
• リアルタイム進捗表示: アップロード速度、進捗率、残り時間を表示
• 自動形式チェック: アップロード後、ffprobeによる動画形式の自動検証
• 受領票自動生成: アップロード完了時に受領票HTMLを生成
• 管理画面: アップロードされたファイル一覧の表示・検索機能
• SHA-256チェックサム: ファイルの完全性を保証

必須形式（デフォルト設定）

• コンテナ: QuickTime/MOV (.mov)
• 映像コーデック: ProRes (prores, prores_ks, prores_aw)
• 解像度: 1920x1080
• フレームレート: 23.98/24/29.97/30 fps
• 音声コーデック: PCM 16bit/24bit
• サンプルレート: 48kHz

プロジェクト構成

.
├── app/                    # フロントエンド
│   ├── index.html         # 学生用アップロードUI
│   └── admin.html         # 管理者用一覧画面
├── nginx/                 # Nginx設定
│   └── uploader.conf      # アップローダー用のnginx設定スニペット
├── scripts/               # デプロイスクリプト
│   └── deploy.sh          # システム全体のデプロイスクリプト
└── tus-hooks/             # TUSフック
    └── post-finish        # アップロード完了時の処理スクリプト

前提条件

サーバー環境

• Linux サーバー（Ubuntu/Debian推奨）
• Nginx
• tusd (TUS Protocol Server) - https://github.com/tus/tusd
• ffmpeg/ffprobe
• jq (JSON処理)
• sha256sum

サーバー側のディレクトリ構造

/var/www/uploader/          # Web UIの配置先
/var/tod-k/
  ├── uploads/              # tusdがアップロードファイルを保存（-upload-dir で指定）
  └── archive/              # post-finishフックで整理されたファイル群
      ├── receipt/          # 受領票HTML
      ├── meta/             # ffprobeのJSON出力
      ├── hash/             # SHA-256チェックサムファイル
      ├── uploads.tsv       # アップロード履歴（TSV形式）
      └── <ID>__<displayname>.<ext>  # uploadsからのハードリンク
/usr/local/todk-hooks/      # tusdフックスクリプト
  └── post-finish           # アップロード完了時のフックスクリプト
/etc/nginx/snippets/        # nginx設定スニペット
  └── uploader.conf         # アップローダー設定

インストールと設定

1. 依存パッケージのインストール

# Ubuntu/Debian
sudo apt update
sudo apt install -y nginx ffmpeg jq

# tusd のインストール (最新版を https://github.com/tus/tusd/releases から取得)
wget https://github.com/tus/tusd/releases/download/v2.x.x/tusd_linux_amd64.tar.gz
tar -xzf tusd_linux_amd64.tar.gz
sudo mv tusd_linux_amd64/tusd /usr/local/bin/
sudo chmod +x /usr/local/bin/tusd

2. プロジェクトのデプロイ

# リポジトリをクローン
git clone <repository-url> /srv/tod-k
cd /srv/tod-k

# デプロイスクリプトを実行（root権限が必要）
sudo bash scripts/deploy.sh

デプロイスクリプトは以下を実行します:

1. nginx設定スニペットの配置
2. Web UIの配置
3. アーカイブディレクトリの作成
4. post-finishフックの配置と実行権限設定

3. tusd の起動

# systemdサービスとして設定する例
sudo tee /etc/systemd/system/tusd.service > /dev/null <<'EOF'
[Unit]
Description=Tusd Upload Server
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
ExecStart=/usr/local/bin/tusd \
  -behind-proxy \
  -base-path /files/ \
  -upload-dir /var/tod-k/uploads \
  -hooks-dir /usr/local/todk-hooks \
  -hooks-enabled-events post-finish
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable tusd
sudo systemctl start tusd

4. Nginx の設定

サーバーブロック内に以下を追加:

server {
    listen 80;
    server_name your-domain.com;

    # TOD-K アップローダー設定を読み込む
    include /etc/nginx/snippets/uploader.conf;

    # tusd へのプロキシ
    location /files/ {
        proxy_pass http://localhost:1080/files/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # アップロードのタイムアウト設定
        proxy_request_buffering off;
        proxy_buffering off;
        client_max_body_size 0;
    }
}

nginxを再起動:

sudo nginx -t
sudo systemctl reload nginx

使用方法

学生側（アップロード）

1. ブラウザで http://your-domain.com/uploader/ にアクセス
2. 作品タイトル、学籍番号、氏名を入力
3. 動画ファイルを選択
4. 「アップロード開始」ボタンをクリック
5. アップロード完了後、受領票が表示されるのでPDF保存または印刷

管理者側（一覧確認）

1. ブラウザで http://your-domain.com/uploader/admin.html にアクセス
2. アップロードされたファイルの一覧を確認
3. 検索機能で受付ID、タイトル、学籍番号、氏名で絞り込み可能
4. 受領票リンクから各ファイルの詳細を確認

ファイル処理フロー

1. アップロード開始: クライアントがTUS POSTリクエストでアップロードを開始
2. チャンク送信: 8MBチャンクでPATCHリクエストを繰り返し送信
3. アップロード完了: tusdが post-finish フックを実行
4. post-finishフック処理:
   • ファイルをアーカイブディレクトリにハードリンク
   • ffprobeでメタデータ取得
   • 形式チェック（ProRes/1920x1080/fps/PCM 48kHz等）
   • SHA-256チェックサム計算
   • 受領票HTML生成
   • uploads.tsvに記録
5. 受領票表示: クライアントが受領票の生成完了をポーリングで検知し表示

カスタマイズ

形式チェック条件の変更

tus-hooks/post-finish の形式チェックロジックを編集してください:

• 解像度チェック（現在: 1920x1080）
• コーデックチェック（現在: ProRes系）
• フレームレートチェック（現在: 23.98/24/29.97/30 fps）
• 音声形式チェック（現在: PCM 48kHz）

UI のカスタマイズ

• app/index.html: アップロード画面のデザイン・文言
• app/admin.html: 管理画面のデザイン・文言

トラブルシューティング

アップロードが失敗する

• tusdが起動しているか確認: systemctl status tusd
• nginxのエラーログを確認: tail -f /var/log/nginx/error.log
• ファイアウォール設定を確認

受領票が生成されない

• /tmp/tusd-debug.log を確認
• ffprobe/jq/sha256sumがインストールされているか確認
• /usr/local/todk-hooks/post-finish の実行権限を確認
• /var/tod-k/archive/ ディレクトリの書き込み権限を確認

形式チェックがNG判定になる

• /var/tod-k/archive/meta/<ID>.json のffprobe出力を確認
• /tmp/tusd-ffprobe.log のエラーログを確認

ライセンス

MIT License

Copyright (c) 2025 馬場一幸 (Kazuyuki Baba)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

作者

馬場一幸 (Kazuyuki Baba)

TOD-K ver.1.0