add PDD workflow: CLAUDE.md, PDD.md, sprint spec with active symlink

2026-07-09 23:57:04 +08:00
parent 9c81befaa2
commit 1e1eec1ecd
6 changed files with 346 additions and 0 deletions
@@ -0,0 +1,152 @@
+# t-youtube Configuration Guide
+
+## Environment Variables
+
+### Backend (.env)
+```bash
+# Database path
+DB_DIR=/volume1/docker/t-youtube/backend
+
+# API Token (for write operations)
+API_TOKEN=<your-api-token>
+
+# DeepSeek API (for summarization)
+DEEPSEEK_API_KEY=<your-key>
+
+# YouTube Data API v3
+GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json
+```
+
+### Docker Compose
+```yaml
+version: "3"
+services:
+  t-youtube:
+    build: .
+    ports:
+      - "8001:8001"
+    environment:
+      - DB_DIR=/backend/data
+      - API_TOKEN=<your-token>
+      - DEEPSEEK_API_KEY=<your-key>
+    volumes:
+      - ./backend/data:/backend/data
+```
+
+## API Token Management
+
+### Generation
+```bash
+python3 -c "import secrets; print('api-' + secrets.token_urlsafe(32))"
+```
+
+### Frontend Setup
+- First-time users see a token setup modal
+- Token stored in localStorage
+- Bearer token sent with all API write requests
+
+### Backend Validation
+- Middleware checks `Authorization: Bearer <token>` for POST/PATCH/DELETE on `/api/*`
+- Returns 401 JSON for invalid tokens
+- GET endpoints remain open to authenticated frontend users
+
+## Database Management
+
+### Location
+- **Path**: `/volume1/docker/t-youtube/backend/t_youtube.db`
+- **Type**: SQLite (aiosqlite)
+- **Backup**: Copy the `.db` file before any schema changes
+
+### Schema Migrations
+- Use `sqlite3` CLI or a migration script
+- Always add indexes after schema changes
+- Example:
+  ```bash
+  sqlite3 t_youtube.db "CREATE INDEX IF NOT EXISTS idx_x ON table(column);"
+  ```
+
+### Daily Sync Configuration
+
+#### Cron Job
+```bash
+# Runs every day at 3 AM
+0 3 * * * /path/to/run_sync.py >> /var/log/t-youtube-sync.log 2>&1
+```
+
+#### Fetcher Settings
+- **RSS**: Free, unlimited, ~2000 channels
+- **YouTube Data API v3**: ~50 units per sync
+- **Rotation**: Fetches in slices to avoid timeouts
+- **Retry**: Automatic retry on failure
+
+#### Summarizer Settings
+- **Model**: `deepseek-chat` via DeepSeek API
+- **Timeout**: 30 seconds per video
+- **Fallback**: Video description if transcript unavailable
+- **Language**: Follows content language (Chinese → Chinese summary)
+
+## Authelia Integration
+
+### Authentication Flow
+1. User accesses protected domain
+2. Caddy forwards request to Authelia (`127.0.0.1:9092`)
+3. Authelia checks session/2FA
+4. If no session → redirect to `auth.jimmygan.com`
+5. If session exists → return 200 (allowed)
+
+### 2FA Methods
+- **WebAuthn (Primary)**: Passkey via iCloud Keychain/Bitwarden
+- **TOTP (Fallback)**: Time-based one-time password
+
+### Configuration
+- **Address**: `127.0.0.1:9092`
+- **Database**: SQLite (`/volume1/docker/authelia/config/db.sqlite3`)
+- **LDAP Backend**: LLDAP (`lldap:3890`)
+- **Session**: 1 hour expiration, 5 minute inactivity timeout
+
+### Restart Authelia
+```bash
+cd /volume1/docker/authelia && /usr/local/bin/docker compose restart authelia
+```
+
+## Caddy Configuration
+
+### VPS Caddy (Public)
+- **Port**: 443
+- **TLS**: Let's Encrypt (HTTP-01)
+- **Authelia**: `forward_auth 100.78.131.124:9092`
+- **DNS**: dnsmasq → VPS Tailscale IP `100.109.198.126`
+
+### NAS Caddy (Local/Tailscale)
+- **Port**: 8443 (fallback due to SNI bug)
+- **TLS**: Cloudflare DNS-01
+- **Authelia**: `forward_auth 127.0.0.1:9092`
+- **SNI Bug**: Per-site `tls` blocks cause cert routing issues
+- **Workaround**: Global TLS config + dnsmasq → VPS Tailscale IP
+
+### Reloading Caddy
+```bash
+# VPS
+ssh caddy-vps "sudo systemctl reload caddy"
+
+# NAS
+cd /volume1/docker/caddy && /usr/local/bin/docker compose restart caddy
+```
+
+## Monitoring & Health
+
+### Health Check
+```bash
+curl -s https://yt.jimmygan.com/api/health
+# Expected: {"status": "ok"}
+```
+
+### Sync Status
+- Check `run_sync.py` logs in `/var/log/t-youtube-sync.log`
+- Monitor DB for new videos/summaries
+- Verify cron job is active: `crontab -l`
+
+### Database Size
+```bash
+ls -lh /volume1/docker/t-youtube/backend/t_youtube.db
+```