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

> Learn how to configure Douban proxy settings in LunaTV using environment variables, admin API, or client localStorage for global, site-wide, or per-user control.

- Repository: [MoonTechLab/LunaTV](https://github.com/MoonTechLab/LunaTV)
- Tags: how-to-guide
- Published: 2026-09-08

---

**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`](https://github.com/MoonTechLab/LunaTV/blob/main/src/lib/config.ts) (lines 211-218)
2. **Admin API** — Runtime database updates via [`src/app/api/admin/site/route.ts`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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:

```dotenv

# 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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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:

```bash
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:

```javascript
// 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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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`](https://github.com/MoonTechLab/LunaTV/blob/main/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.