How to Configure Douban Proxy Settings in LunaTV: Environment, Admin, and Client Methods

LunaTV configures Douban proxy settings through a three-tier system: environment variables for global defaults, the admin API for runtime site-wide changes, and browser localStorage for per-user overrides.

Setting up Douban proxy settings in LunaTV allows you to bypass CORS restrictions, optimize CDN routing, or route requests through custom gateways when accessing Douban's media database. The MoonTechLab/LunaTV repository implements a flexible cascading configuration system that prioritizes client-side preferences while falling back to server-defined defaults.

Understanding the Three-Level Configuration System

LunaTV's proxy configuration operates at three distinct levels, each offering different scope and persistence:

1. Environment Variables — Global defaults set during server startup in src/lib/config.ts (lines 211-218)
2. Admin API — Runtime database updates via src/app/api/admin/site/route.ts (lines 31-99) that persist across restarts
3. Browser localStorage — Client-side overrides in src/lib/douban.client.ts (lines 95-117) that apply only to the current user session

The effective configuration resolves in reverse priority: localStorage overrides admin settings, which override environment variables.

Method 1: Configure via Environment Variables

For persistent, server-wide defaults, define the proxy behavior in your environment before starting the Next.js server.

Available Proxy Types

The NEXT_PUBLIC_DOUBAN_PROXY_TYPE variable accepts these values:

• direct — Connect to Douban API without intermediary
• cors-proxy-zwei — Use LunaTV's dedicated CORS proxy
• cmliussss-cdn-tencent — Route through Tencent CDN mirror
• cmliussss-cdn-ali — Route through Alibaba Cloud CDN mirror
• cors-anywhere — Use generic CORS-anywhere service
• custom — Use the URL specified in NEXT_PUBLIC_DOUBAN_PROXY

Setting Variables in .env

Add these lines to your .env.local or hosting platform environment:

# Use Tencent CDN for faster China access

NEXT_PUBLIC_DOUBAN_PROXY_TYPE=cmliussss-cdn-tencent

# Required only when using 'custom' type

NEXT_PUBLIC_DOUBAN_PROXY=https://my-proxy.example.com/

Restart the Next.js server after editing. The values are read once during initialization in src/lib/config.ts and become the baseline configuration.

Method 2: Update via Admin API for Runtime Changes

For immediate updates without server restarts, the admin panel posts configuration changes to the database through the site management API.

API Endpoint and Authentication

The endpoint POST /api/admin/site in src/app/api/admin/site/route.ts handles persistent configuration updates. The handler validates fields including DoubanProxyType and DoubanProxy (lines 31-55) and stores them in the database, taking effect immediately for all subsequent requests.

Example cURL Request

Update the proxy settings programmatically:

curl -X POST https://your-lunatv.com/api/admin/site \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_AUTH_COOKIE" \
  -d '{
    "SiteName": "LunaTV",
    "Announcement": "Welcome!",
    "SearchDownstreamMaxPage": 5,
    "SiteInterfaceCacheTime": 7200,
    "DoubanProxyType": "custom",
    "DoubanProxy": "https://my-proxy.example.com/",
    "DoubanImageProxyType": "custom",
    "DoubanImageProxy": "https://my-image-proxy.example.com/",
    "DisableYellowFilter": false,
    "FluidSearch": true,
    "EnableWebLive": false
  }'

This mirrors the JSON payload structure validated in the route handler, allowing you to switch proxy types or update custom URLs without touching environment files.

Method 3: Browser localStorage for Per-User Overrides

For debugging or testing alternative proxies without affecting other users, LunaTV checks localStorage keys before applying server defaults.

Client-Side Debugging

Execute this in browser DevTools to override the proxy for your session:

// Use a specific CORS proxy implementation
localStorage.setItem('doubanDataSource', 'cors-proxy-zwei');

// Or provide a custom proxy endpoint
localStorage.setItem('doubanProxyUrl', 'https://my-proxy.example.com/');

// Reload to apply changes
location.reload();

The getDoubanProxyConfig() function in src/lib/douban.client.ts (lines 95-117) reads these keys and supersedes server configuration, enabling rapid testing of different routing strategies without admin access.

How the Proxy Selection Logic Works

When fetching Douban data, LunaTV follows this resolution chain:

1. getDoubanProxyConfig() gathers the effective proxyType and proxyUrl by checking localStorage first, then API/site config, then environment defaults
2. Request routing functions (getDoubanCategories, getDoubanList, getDoubanRecommends) switch on the resolved proxyType:
   • Direct mode calls api.douban.com without modification
   • CDN modes prefix requests with cmliussss-cdn-tencent or cmliussss-cdn-ali endpoints
   • CORS modes route through cors-proxy-zwei or cors-anywhere intermediaries
   • Custom mode inserts your specified proxyUrl as the base path
   • Fallback routes to internal /api/douban/... endpoints if no valid type matches

This architecture ensures that network restrictions or geographic latency issues can be resolved through administration while preserving flexibility for end-user customization.

Summary

• Environment variables (NEXT_PUBLIC_DOUBAN_PROXY_TYPE, NEXT_PUBLIC_DOUBAN_PROXY) set permanent defaults in src/lib/config.ts that apply server-wide
• Admin API (/api/admin/site) persists runtime changes to the database, affecting all users immediately without restarts
• localStorage (doubanDataSource, doubanProxyUrl) provides client-side overrides for individual debugging or testing
• Six proxy types are supported: direct, cors-proxy-zwei, cmliussss-cdn-tencent, cmliussss-cdn-ali, cors-anywhere, and custom
• Configuration resolution follows a cascading priority: localStorage → Admin API → Environment variables

Frequently Asked Questions

What proxy types are supported in LunaTV's Douban integration?

LunaTV supports six proxy modes defined in the configuration system: direct for unproxied connections, cors-proxy-zwei and cors-anywhere for CORS bypass services, cmliussss-cdn-tencent and cmliussss-cdn-ali for China-optimized CDN routing, and custom for user-defined proxy endpoints. These values are validated in src/lib/config.ts and processed by getDoubanProxyConfig() in the client library.

How do I switch back to direct Douban connections?

Set NEXT_PUBLIC_DOUBAN_PROXY_TYPE=direct in your environment variables, send "DoubanProxyType": "direct" via the admin API POST to /api/admin/site, or execute localStorage.setItem('doubanDataSource', 'direct') in the browser console followed by a page reload. Direct mode bypasses all intermediaries and connects straight to Douban's API endpoints.

Why are my custom proxy settings not taking effect?

Verify the configuration level you're modifying isn't being overridden by a higher-priority layer. Environment variables are superseded by admin API settings stored in the database, which are in turn overridden by localStorage values. Check src/lib/douban.client.ts lines 95-117 to confirm no localStorage keys are present, and ensure you've restarted the server when modifying .env files.

Where does LunaTV store admin API proxy configurations?

The POST /api/admin/site handler in src/app/api/admin/site/route.ts (lines 31-99) persists DoubanProxyType and DoubanProxy values to the application's database as part of the site configuration object. Unlike environment variables, these settings survive server restarts and take effect immediately without requiring a restart, as the client fetches current configuration on each request.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}