跳到主要内容

在 Nginx 与 HTTPS 后部署 SkillFlaw

在 Linux 服务器上部署 SkillFlaw 时，建议保留现有服务拆分方式，并让 Nginx 作为前置入口层。

本指南默认你采用与 docker/docker-compose.yml 一致的运行契约：

  • 后端 API 在 7860
  • 前端 UI 在 3001
  • 可选的独立文档服务在 3002

由 Nginx 负责对外 HTTPS、主机名路由与请求限制。

适用场景​

当你想采用以下这些部署形态时，可以使用本指南：

  1. 完整 Web 部署：前端 + 后端，文档按需使用独立域名
  2. API 优先部署：只暴露后端，文档按需独立对外

如果你还在初始化整个运行栈，请先阅读 用于部署的 SkillFlaw 安装说明 与 SkillFlaw 部署架构。

前置条件​

  • 目标机器上已经有一个运行中的 SkillFlaw 部署
  • 一台支持 Nginx 的 Debian / Ubuntu 风格 Linux 主机
  • 一个公网域名，且你有权修改 DNS 记录
  • DNS 已经指向该服务器公网 IP
  • 可通过系统包安装 Certbot

参考 compose 栈中的本地上游地址为：

服务本地地址用途
Frontendhttp://127.0.0.1:3001Web UI 和 /playground/:id/ 这类可共享 Playground 路由
Backendhttp://127.0.0.1:7860/health、/api/*、/api/v1/mcp/streamable、webhook 与 run 端点
Docshttp://127.0.0.1:3002可选的独立文档服务

选择公网路由模型​

最清晰的生产方案是使用独立主机名：

  • app.example.com -> 前端
  • api.example.com -> 后端
  • docs.example.com -> 文档（可选）

这样可以把浏览器 UI、程序化 API 流量和文档访问彻底分开。

安装并启用 Nginx​

  1. 安装 Nginx。


    _10
    sudo apt update
    _10
    sudo apt install nginx -y

  2. 启动并设置开机自启。


    _10
    sudo systemctl enable --now nginx

为 SkillFlaw 配置 Nginx​

下面的示例使用三个虚拟主机，不需要的可以删掉。

  1. 创建站点配置文件。


    _10
    sudo nano /etc/nginx/sites-available/skillflaw.conf

  2. 粘贴如下配置，并将示例域名替换为你的真实域名。


    _53
    server {
    _53
    listen 80;
    _53
    server_name app.example.com;
    _53
    _53
    client_max_body_size 100M;
    _53
    _53
    location / {
    _53
    proxy_pass http://127.0.0.1:3001;
    _53
    proxy_http_version 1.1;
    _53
    proxy_set_header Host $host;
    _53
    proxy_set_header X-Real-IP $remote_addr;
    _53
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    _53
    proxy_set_header X-Forwarded-Proto $scheme;
    _53
    proxy_set_header Upgrade $http_upgrade;
    _53
    proxy_set_header Connection "upgrade";
    _53
    }
    _53
    }
    _53
    _53
    server {
    _53
    listen 80;
    _53
    server_name api.example.com;
    _53
    _53
    client_max_body_size 100M;
    _53
    _53
    location / {
    _53
    proxy_pass http://127.0.0.1:7860;
    _53
    proxy_http_version 1.1;
    _53
    proxy_set_header Host $host;
    _53
    proxy_set_header X-Real-IP $remote_addr;
    _53
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    _53
    proxy_set_header X-Forwarded-Proto $scheme;
    _53
    proxy_set_header Upgrade $http_upgrade;
    _53
    proxy_set_header Connection "upgrade";
    _53
    proxy_connect_timeout 60s;
    _53
    proxy_send_timeout 60s;
    _53
    proxy_read_timeout 300s;
    _53
    proxy_buffering off;
    _53
    proxy_request_buffering off;
    _53
    }
    _53
    }
    _53
    _53
    server {
    _53
    listen 80;
    _53
    server_name docs.example.com;
    _53
    _53
    location / {
    _53
    proxy_pass http://127.0.0.1:3002;
    _53
    proxy_set_header Host $host;
    _53
    proxy_set_header X-Real-IP $remote_addr;
    _53
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    _53
    proxy_set_header X-Forwarded-Proto $scheme;
    _53
    }
    _53
    }

  3. 启用站点并校验配置语法。


    _10
    sudo ln -sf /etc/nginx/sites-available/skillflaw.conf /etc/nginx/sites-enabled/skillflaw.conf
    _10
    sudo nginx -t

  4. 重载 Nginx。


    _10
    sudo systemctl reload nginx

使用 Certbot 申请 TLS 证书​

  1. 安装 Certbot 与 Nginx 插件。


    _10
    sudo apt install certbot python3-certbot-nginx -y

  2. 为实际对外暴露的主机名申请证书。


    _10
    sudo certbot --nginx -d app.example.com -d api.example.com -d docs.example.com

    如果你暴露的主机名更少，请删掉多余的 -d 参数。

  3. 让 Certbot 自动更新 Nginx 配置，并按需选择是否将 HTTP 重定向到 HTTPS。

  4. 验证自动续期是否已启用。


    _10
    systemctl list-timers | grep certbot

验证公网入口​

TLS 启用后，按你的部署形态验证这些地址：

  • https://app.example.com
  • https://api.example.com/health
  • https://api.example.com/api/v1/mcp/streamable
  • https://docs.example.com

运维说明​

  • SKILLFLAW_SECRET_KEY_FILE 必须在后端运行环境中挂载为真实文件；Nginx 不会改变这个要求。
  • SKILLFLAW_CONFIG_DIR 应放在持久化存储上。
  • 如果你只暴露 API，可只对外开放后端域名，把前端与文档保留为私有或关闭。
  • 如果你公开暴露 MCP，同样要使用与其他后端 API 一致的认证控制。

另请参阅​