部署指南

部署架构

flowchart TB
    Internet -->|HTTPS| Nginx
    Nginx -->|反向代理| API["Cloud API (8766 HTTP)"]
    Nginx -->|反向代理| WS["Cloud WS (8765 WS)"]
    Nginx -->|反向代理| Console["Console (8770)"]
    Nginx -->|反向代理| Site["Public Site (8771)"]

环境要求

组件	版本要求
Python	≥ 3.11
操作系统	Ubuntu 22.04 / Debian 12 / Windows Server 2022
Nginx（推荐）	≥ 1.24
Supervisor（推荐）	≥ 4.2

生产部署步骤

1. 准备环境

# Ubuntu / Debian
apt update && apt install -y python3 python3-pip python3-venv nginx supervisor

# 创建运行用户
useradd -r -s /bin/false janpnp

2. 部署代码

# 创建目录
mkdir -p /opt/janpnp/web-server
chown janpnp:janpnp /opt/janpnp/web-server

# 以 janpnp 用户部署
su - janpnp -c "
cd /opt/janpnp/web-server
git clone <repo-url> .

# 创建虚拟环境并安装依赖
cd api
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 复制并编辑环境变量
cp .env.example .env
"

3. 配置环境变量

编辑 api/.env，参考以下生产配置：

CLOUD_ENV=production
CLOUD_WS_HOST=127.0.0.1
CLOUD_WS_PORT=8765
CLOUD_HTTP_HOST=127.0.0.1
CLOUD_HTTP_PORT=8766
CLOUD_DEVICE_TOKEN=<生成一个 64 字符随机字符串>
CLOUD_JWT_SECRET=<生成一个至少 32 字符随机字符串>
CLOUD_AUTH_USERS={"admin":{"password":"<强密码>","role":"admin","display_name":"JanPNP 管理员"}}
CLOUD_CORS_ORIGINS=https://janpnp.otodone.com,https://console.janpnp.otodone.com
CLOUD_FIRMWARE_DIR=/opt/janpnp/web-server/api/firmware
CLOUD_LOG_DIR=/var/log/janpnp
CLOUD_FIRMWARE_UPLOAD_MAX_BYTES=2097152

# 微信小程序（可选）
WECHAT_APP_ID=your-wechat-app-id
WECHAT_APP_SECRET=your-wechat-app-secret

安全警告：生产环境必须修改 CLOUD_JWT_SECRET、CLOUD_DEVICE_TOKEN 和 CLOUD_AUTH_USERS 中的默认值。配置文件中的 config.validate_production_config() 会在 CLOUD_ENV=production 时自动校验。

4. 配置 Supervisor

创建 /etc/supervisor/conf.d/janpnp-cloud.conf：

[program:janpnp-cloud]
command=/opt/janpnp/web-server/api/venv/bin/python server.py
directory=/opt/janpnp/web-server/api
user=janpnp
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/log/janpnp/cloud.err.log
stdout_logfile=/var/log/janpnp/cloud.out.log
environment=CLOUD_ENV="production"

# 创建日志目录
mkdir -p /var/log/janpnp
chown janpnp:janpnp /var/log/janpnp

# 加载配置
supervisorctl reread && supervisorctl update

5. 配置 Nginx 反向代理

创建 /etc/nginx/sites-available/api.janpnp.otodone.com：

server {
    listen 443 ssl http2;
    server_name api.janpnp.otodone.com;

    ssl_certificate /etc/ssl/certs/janpnp/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/janpnp/privkey.pem;

    # HTTP API
    location / {
        proxy_pass http://127.0.0.1:8766;
        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;
    }

    # 固件大文件下载优化
    location /api/v1/firmware/ {
        proxy_pass http://127.0.0.1:8766;
        proxy_buffering on;
        proxy_buffer_size 8k;
        proxy_buffers 8 64k;
        proxy_max_temp_file_size 0;
    }
}

# WebSocket 子域名
server {
    listen 443 ssl http2;
    server_name ws.janpnp.otodone.com;

    ssl_certificate /etc/ssl/certs/janpnp/fullchain.pem;
    ssl_certificate_key /etc/ssl/private/janpnp/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8765;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

同样为 Console 和 Site 服务配置独立 Nginx virtual host。

6. 启动服务

supervisorctl start janpnp-cloud

# 验证健康检查
curl https://api.janpnp.otodone.com/api/v1/health

预期响应：

{
  "status": "ok",
  "service": "janpnp-cloud",
  "version": "2.0.0",
  "device_count": 0,
  "uptime": 42
}

7. 部署 Console 与 Site

Console 和 Site 同为 aiohttp 静态文件服务，部署方式与 Cloud API 类似：

# Console
cd /opt/janpnp/web-server/console
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 启动（同样通过 Supervisor 管理）
python app.py

# Site（官方网站）
cd /opt/janpnp/web-server/home
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

运维命令

# Supervisor 管理
supervisorctl status              # 查看所有服务状态
supervisorctl restart janpnp-cloud # 重启云网关
supervisorctl tail -f janpnp-cloud # 查看实时日志

# 日志查看
tail -f /var/log/janpnp/cloud.out.log
tail -f /var/log/janpnp/cloud.err.log

# Nginx
nginx -t                         # 测试配置
nginx -s reload                  # 重载配置

构建验证

发布前至少执行：

# 启动服务并验证健康检查
python server.py &
curl http://127.0.0.1:8766/api/v1/health

# 运行冒烟测试
python tools/smoke_test.py

# 使用模拟设备验证端到端流程
python tools/mock_device.py --device-id test-001 &
curl http://127.0.0.1:8766/api/v1/devices

验收项包括：

服务正常启动
设备可注册
API 路由可达
固件清单可读
CORS 头正确
JWT 认证生效