ds2api/DEPLOY.en.md

DS2API Deployment Guide

Language: 中文 | English

This document covers all supported DS2API deployment methods.

---

Table of Contents

• Vercel Deployment (Recommended)
• Docker Deployment (Recommended)
• Local Development
• Production Deployment
• FAQ

---

Vercel Deployment (Recommended)

One-click deployment

Steps

1. Click the deploy button

   • Sign in to GitHub
   • Authorize Vercel access

2. Set environment variables

   • DS2API_ADMIN_KEY: Admin console password (required)

3. Wait for deployment

   • Vercel builds and deploys automatically
   • You will receive a deployment URL

4. Configure accounts

   • Visit https://your-project.vercel.app/admin
   • Log in with the admin key
   • Add DeepSeek accounts
   • Set custom API keys

5. Sync configuration

   • Click "Sync to Vercel"
   • The first sync requires a Vercel token and project ID
   • After sync, the configuration is persisted

Get Vercel credentials

Vercel token:

1. Visit https://vercel.com/account/tokens
2. Click "Create Token"
3. Set a name and expiration
4. Copy the token

Project ID:

1. Open your Vercel project
2. Go to Settings → General
3. Copy the "Project ID"

---

Local Development

Requirements

• Python 3.9+
• Node.js 18+ (WebUI development)
• pip

Quick start

# 1. Clone the repo
git clone https://github.com/CJackHwang/ds2api.git
cd ds2api

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Configure accounts
cp config.example.json config.json
# Edit config.json and fill in DeepSeek account info

# 4. Start the service
python dev.py

Config example

{
  "keys": ["my-api-key-1", "my-api-key-2"],
  "accounts": [
    {
      "email": "your-email@example.com",
      "password": "your-password",
      "token": ""
    },
    {
      "mobile": "12345678901",
      "password": "your-password",
      "token": ""
    }
  ]
}

Notes:

• keys: Custom API keys for calling the service
• accounts: DeepSeek Web accounts
  • Supports email or mobile login
  • Leave token blank; it will be fetched automatically

WebUI development

# Enter the WebUI directory
cd webui

# Install dependencies
npm install

# Start the dev server
npm run dev

The WebUI dev server runs on http://localhost:5173 and proxies API requests to http://localhost:5001.

WebUI build

Build artifacts are located in static/admin/.

Automatic build (recommended):

• Vercel builds the WebUI during deployment (see vercel.json buildCommand)
• The GitHub Actions WebUI build workflow is disabled
• static/admin/ build artifacts are no longer committed

Manual build:

# Option 1: use script
./scripts/build-webui.sh

# Option 2: run directly
cd webui
npm install
npm run build

Contributor note: No manual build is required after modifying WebUI; Vercel deploys will build it automatically.

---

Docker Deployment (Recommended)

Docker uses a non-invasive, decoupled design:

• Dockerfile executes standard Python steps and avoids hardcoded project configs
• WebUI is built during image build (for non-Vercel deployments)
• Configuration lives in environment variables and .env
• Rebuild the image to update code without touching Docker config

Quick start (Docker Compose)

# 1. Copy the environment template
cp .env.example .env
# Edit .env with DS2API_ADMIN_KEY and DS2API_CONFIG_JSON

# 2. Start the service
docker-compose up -d

# 3. Check logs
docker-compose logs -f

# 4. Rebuild after code updates
docker-compose up -d --build

Mount a config file

To use config.json instead of environment variables:

# docker-compose.yml
services:
  ds2api:
    build: .
    ports:
      - "5001:5001"
    environment:
      - DS2API_ADMIN_KEY=your-admin-key
    volumes:
      - ./config.json:/app/config.json:ro
    restart: unless-stopped

Docker CLI deployment

# Build the image
docker build -t ds2api:latest .

# Run with env variables
docker run -d \
  --name ds2api \
  -p 5001:5001 \
  -e DS2API_ADMIN_KEY=your-admin-key \
  -e DS2API_CONFIG_JSON='{"keys":["api-key"],"accounts":[...]}' \
  --restart unless-stopped \
  ds2api:latest

# Or mount a config file
docker run -d \
  --name ds2api \
  -p 5001:5001 \
  -e DS2API_ADMIN_KEY=your-admin-key \
  -v $(pwd)/config.json:/app/config.json:ro \
  --restart unless-stopped \
  ds2api:latest

Development mode (hot reload)

# Use the dev compose file to enable hot reload
docker-compose -f docker-compose.dev.yml up

Development mode:

• Source code is mounted into the container
• Log level set to DEBUG
• Reads local config.json

Maintenance commands

# Check container status
docker-compose ps

# View logs
docker-compose logs -f ds2api

# Restart
docker-compose restart

# Stop
docker-compose down

# Full rebuild (clear cache)
docker-compose down
docker-compose build --no-cache
docker-compose up -d

---

Production Deployment

Using systemd (Linux)

1. Create the service file

sudo nano /etc/systemd/system/ds2api.service

[Unit]
Description=DS2API Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/ds2api
ExecStart=/usr/bin/python3 app.py
Restart=always
RestartSec=10
Environment=PORT=5001
Environment=DS2API_ADMIN_KEY=your-admin-key

[Install]
WantedBy=multi-user.target

2. Start the service

sudo systemctl daemon-reload
sudo systemctl enable ds2api
sudo systemctl start ds2api

3. Check status

sudo systemctl status ds2api
sudo journalctl -u ds2api -f

Nginx reverse proxy

server {
    listen 80;
    server_name api.yourdomain.com;

    # SSL configuration (recommended)
    # listen 443 ssl http2;
    # ssl_certificate /path/to/cert.pem;
    # ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:5001;
        proxy_http_version 1.1;
        
        # Disable buffering for SSE
        proxy_buffering off;
        proxy_cache off;
        
        # Connection settings
        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;
        
        # SSE timeouts
        proxy_read_timeout 300s;
        proxy_send_timeout 300s;
        
        # Chunked transfer
        chunked_transfer_encoding on;
        tcp_nopush on;
        tcp_nodelay on;
        keepalive_timeout 120;
    }
}

---

FAQ

Q: What if account validation fails?

A: Check the following:

1. Confirm the DeepSeek account password is correct
2. Ensure the account is not banned or requires verification
3. Log in once in a browser
4. Check logs for detailed errors

Q: Streaming responses disconnect?

A:

1. Check Nginx / reverse proxy config and ensure proxy_buffering is off
2. Increase proxy_read_timeout
3. Verify network stability

Q: Configuration lost after Vercel deploy?

A:

1. Ensure you clicked "Sync to Vercel"
2. Verify the Vercel token is valid and unexpired
3. Ensure the project ID is correct

Q: How to update to the latest version?

Local deployment:

git pull origin main
pip install -r requirements.txt
# Restart the service

Docker deployment:

# Pull the latest code
git pull origin main

# Rebuild and start (Docker config unchanged)
docker-compose up -d --build

Vercel deployment:

• The project auto-syncs from GitHub
• Or trigger a redeploy in the Vercel console

Q: How do I view logs?

Local dev:

# Set log level
export LOG_LEVEL=DEBUG
python dev.py

Vercel:

• Vercel console → Project → Deployments → Logs

Q: Token counting is inaccurate?

A: DS2API uses a heuristic estimate (characters / 4). The official OpenAI tokenizer may differ, so treat it as a reference only.

---

Get Help

• GitHub Issues: https://github.com/CJackHwang/ds2api/issues
• Docs: https://github.com/CJackHwang/ds2api