danmu-desktop

Display bullet screen directly on the desktop 在桌面直接顯示彈幕

中文說明

Overview

This project is divided into two parts:

1. Danmu-Desktop
   • Client-side application that runs on your computer to display danmu
   • Currently supports Windows and MacOS
   • Available as both installer and portable version

2. Server
   • Creates a web interface for danmu input
   • Manages danmu delivery to connected clients
   • Includes admin panel for configuration, source fingerprint logging, and history review

Installation & Usage

Danmu-Desktop Client

1. Download the latest release
2. For MacOS users, run:

   sudo xattr -r -d com.apple.quarantine 'danmu manager.app'

3. Launch the application
4. Enter the server's IP and port (default: 4001)

Server Setup

Option 1: Docker Hub Image (Recommended)

1. Pull and run the image directly (replace the password):

   docker run -d --name danmu-server \
     -p 4000:4000 \
     -p 4001:4001 \
     -e ADMIN_PASSWORD=your_secure_password \
     -v danmu_fonts:/app/server/user_fonts \
     -v danmu_static:/app/server/static \
     -v danmu_logs:/app/server/logs \
     albetyty/danmu-server:latest

   • You can also use a bcrypt hash instead of plaintext:
     • Generate hash: python server/scripts/hash_password.py
     • Set -e ADMIN_PASSWORD_HASHED='<bcrypt-hash>'
   • Server startup now requires at least one of ADMIN_PASSWORD or ADMIN_PASSWORD_HASHED.
   • Multi-arch images published for linux/amd64 and linux/arm64/v8
   • Available tags:
     • latest: stable build from main
     • main: rolling alias of the newest main build
     • <git-sha>: immutable build for a specific commit (see workflow logs)
2. Optional: add --restart unless-stopped for long-running deployments.
3. To update, just pull the latest tag and restart:

   docker pull albetyty/danmu-server:latest
   docker stop danmu-server && docker rm danmu-server
   # rerun the docker run command above

Option 2: Docker Compose

1. Clone the repository:

   git clone https://github.com/guan4tou2/danmu-desktop
   cd danmu-desktop

2. Configure environment variables:

   cp env.example .env
   # Edit .env and set ADMIN_PASSWORD / ADMIN_PASSWORD_HASHED and other settings

3. Start services:

   docker-compose up -d

   • reverse-proxy is exposed on host ports 4000 (HTTP) and 4001 (WebSocket).
   • The Python server is now internal-only behind Nginx in Compose mode.

4. Optional HTTPS mode (web panel):

   # Put cert files first:
   # nginx/certs/fullchain.pem
   # nginx/certs/privkey.pem
   docker-compose --profile https up -d

   • This starts reverse-proxy-https on 80/443 and redirects HTTP to HTTPS.
   • Desktop overlay connection remains on 4001 unless you separately implement WSS for the desktop client flow.

5. To use Redis for rate limiting (optional):

   docker-compose --profile redis up -d

Option 3: Manual Setup

1. Clone the repository:

   git clone https://github.com/guan4tou2/danmu-desktop
   cd danmu-desktop

2. Configure environment:

   cp env.example .env
   vim .env  # Set your admin password and other settings

3. Setup virtual environment and install dependencies:

   cd server
   uv venv
   uv sync

4. Start the server (HTTP + WebSocket):

   # Terminal 1: HTTP server
   PYTHONPATH=.. uv run python -m server.app
   
   # Terminal 2: WebSocket server
   PYTHONPATH=.. uv run python -m server.ws_app

Accessing the Server

• Main interface: http://ip:4000
• Admin panel: http://ip:4000/admin

Environment Variables

Key configuration options (set via .env file or environment variables):

• ADMIN_PASSWORD or ADMIN_PASSWORD_HASHED (at least one required): Admin authentication secret
• PORT: HTTP server port (default: 4000)
• WS_PORT: WebSocket server port (default: 4001)
• SECRET_KEY: Flask secret key (auto-generated if not set)
• TRUSTED_HOSTS: comma-separated allowed hostnames for Host header validation (recommended in production)
• TRUST_X_FORWARDED_FOR: trust X-Forwarded-For for client IP detection (default: false; enable only behind a trusted reverse proxy)
• WS_REQUIRE_TOKEN: require ?token= for dedicated WebSocket clients (default: true)
• WS_AUTH_TOKEN: shared secret token for dedicated WebSocket clients
• WS_MAX_SIZE: maximum incoming WebSocket message size in bytes (default: 1048576)
• WS_MAX_QUEUE: maximum number of incoming WebSocket messages buffered (default: 16)
• WS_WRITE_LIMIT: write buffer limit in bytes for WebSocket connections (default: 32768)
• WEB_WS_ALLOWED_ORIGINS: optional allowlist for browser WebSocket Origin on / route
• RATE_LIMIT_BACKEND: Rate limiter backend - memory or redis (default: memory)
• REDIS_URL: Redis connection URL (required if using Redis backend)
• LOG_LEVEL: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)
• SETTINGS_FILE: path to persisted runtime settings file (optional; defaults to a temp file)

See env.example for all available options.

Security Notes

• GitHub Advanced Security and Dependabot are enabled for this repository.
• OSV scanning runs on push, pull_request, and scheduled jobs via .github/workflows/osv-scanner.yml.
• Frontend lockfile enforces serialize-javascript@7.0.3 through npm overrides to address advisory GHSA-5c6j-r48x-rmvq.

Project Docs / 文件

• docs/README.md – index of technical notes and archives / 技術文件索引。
• DEPLOYMENT.md – production-grade setup instructions / 部署說明。
• README-CH.md – 中文總覽。
• docs/archive/ – historical improvement notes kept for reference / 歷史紀錄。

CI/CD & Docker Hub

• Workflow .github/workflows/docker-build.yml builds and tests the server image on each PR/push.
• Set GitHub secrets DOCKERHUB_USERNAME + DOCKERHUB_TOKEN (Docker Hub access token) to auto-publish DOCKERHUB_USERNAME/danmu-server:latest and a commit-SHA tag whenever main is updated.

Testing & Coverage

• Run tests: make test or make test-verbose
• Generate coverage report: make coverage
  • Console summary via coverage report
  • HTML report at server/htmlcov/index.html

Port Configuration

• 4000: Web interface (HTTP via reverse proxy)
• 4001: Danmu Desktop Client connection (WebSocket via reverse proxy)

References

SAO UI design inspired by SAO-UI-PLAN-LINK-START | Akilar の糖果屋