跳到主要内容

本地开发部署

本文档说明 SkillFlaw 基于源码工作区的本地开发流程，适用于本地开发、联调与文档贡献。

前置工具​

开始前请确保已经安装：

  • git
  • make
  • uv
  • Node.js 与 npm
  • 如需验证 Compose 部署链路，请安装 Docker

1. 准备源码工作区​


_10
git clone https://github.com/cwinux/skillflaw.git
_10
cd skillflaw

复制环境模板：


_10
cp .env.example .env

在初始化前，请先确认以下必需变量有效：

  • SKILLFLAW_DATABASE_URL
  • SKILLFLAW_SECRET_KEY_FILE
  • 你测试所需的外部 API Key

本地 .env 配置清单​

在本地开发场景下，应将核心基础设施配置显式写入 .env，以保证环境行为可预测且可复现。

PostgreSQL​

本地后端开发必须使用 PostgreSQL。请确认 SKILLFLAW_DATABASE_URL 指向当前机器可访问的 PostgreSQL 实例，例如：


_10
SKILLFLAW_DATABASE_URL=postgresql://skillflaw:skillflaw@localhost:5432/skillflaw

如果 SKILLFLAW_DATABASE_URL 中指定的数据库尚不存在，make init_db 会先尝试自动创建该数据库，再导入 schema 和初始化数据。连接串中的 PostgreSQL 用户必须具备 CREATE DATABASE 权限。

如果你还要在本地跑依赖 PostgreSQL 的后端测试，也建议同时配置独立测试库：


_10
SKILLFLAW_TEST_DATABASE_URL=postgresql://skillflaw_test:123456@localhost:5432/skillflaw_test

Redis​

如果本地运行时使用 Redis 缓存，请显式配置缓存模式与 Redis 连接：


_10
SKILLFLAW_CACHE_TYPE=redis
_10
SKILLFLAW_REDIS_HOST=127.0.0.1
_10
SKILLFLAW_REDIS_PORT=6379
_10
SKILLFLAW_REDIS_DB=0
_10
SKILLFLAW_REDIS_CACHE_EXPIRE=3600
_10
SKILLFLAW_REDIS_PASSWORD=

如果本地开发不使用 Redis，请将 SKILLFLAW_CACHE_TYPE 设置为非 Redis 模式，例如 memory，并避免为后端配置不存在的 Redis 连接。

Store 相关配置​

只有在你需要联调 Store 集成，或要验证依赖远端 Store 的上传、下载、点赞等链路时，才需要配置 Store 相关地址。此时至少应确认：


_10
SKILLFLAW_STORE_URL=
_10
SKILLFLAW_DOWNLOAD_WEBHOOK_URL=
_10
SKILLFLAW_LIKE_WEBHOOK_URL=

如果当前本地开发不涉及 Store 功能，这些值可以留空。

本地文件存储​

对于基于源码工作区的本地开发，建议显式指定存储引擎和本地目录，这样工作流文件、技能文件、图片和临时导出文件都会落到可预期的位置：


_10
SKILLFLAW_FLOW_STORE_TYPE=local
_10
SKILLFLAW_FLOW_STORE_LOCAL_PATH=~/data/skillflow/storage/flow
_10
SKILLFLAW_SKILL_STORE_TYPE=local
_10
SKILLFLAW_SKILL_STORE_LOCAL_PATH=~/data/skillflow/storage/skill
_10
SKILLFLAW_PIC_STORE_TYPE=local
_10
SKILLFLAW_PIC_STORE_LOCAL_PATH=~/data/skillflow/storage/pic
_10
SKILLFLAW_TMP_STORE_TYPE=local
_10
SKILLFLAW_TMP_STORE_LOCAL_PATH=~/data/skillflow/storage/tmp

如果你把某个存储切换为 S3，则必须为该存储补齐对应的 bucket、endpoint、region 与访问凭据。

Skill 沙箱 / OpenSandbox​

如果你要在本地验证 Skill 执行、AI 辅助 Skill 流程，或任何依赖沙箱运行时的能力，请显式配置 OpenSandbox 连接：


_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN=localhost:8080
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL=http
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY=
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY=false
_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS=600

这些值必须与后端实际可访问的 OpenSandbox 服务保持一致。如果所在环境使用不同的服务地址、协议或 API Key，请在执行 make backend 前完成更新。

本地开发中的安全沙箱说明​

Skill 运行时执行与 MCP stdio 沙箱执行均通过沙箱服务完成，而不是直接在 SkillFlaw 后端主进程内运行不受信任代码。

  • Skill 执行默认通过 Skill 沙箱服务接入 OpenSandbox。
  • MCP 的 stdio 沙箱执行同样依赖 OpenSandbox，但会独立解析自己的沙箱镜像和运行时工作目录。

在本地联调这些能力时，应把沙箱视为必需运行时依赖，而不是可有可无的附加项。

Skill 如何使用沙箱​

Skill 执行当前默认使用 opensandbox 后端。本地开发至少应确认以下事项：

  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN 指向的 OpenSandbox 服务，SkillFlaw 后端能够访问
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL 与实际服务协议一致
  • 如目标环境启用了鉴权，SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY 与目标环境保持一致
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS 足以覆盖你当前要验证的 Skill 执行时长

如果你还要验证依赖自动安装、长时间运行脚本或文件导出行为，也建议把 Skill 沙箱运行限制显式写入 .env：


_10
SKILLFLAW_SKILL_SANDBOX_CPUS=1.0
_10
SKILLFLAW_SKILL_SANDBOX_MEMORY_MB=512
_10
SKILLFLAW_SKILL_SANDBOX_PIDS_LIMIT=256
_10
SKILLFLAW_SKILL_SANDBOX_TIMEOUT_SECONDS=60
_10
SKILLFLAW_SKILL_SANDBOX_NETWORK=none
_10
SKILLFLAW_SKILL_SANDBOX_READ_ONLY_ROOT=true
_10
SKILLFLAW_SKILL_SANDBOX_TMPFS_ENABLED=true
_10
SKILLFLAW_SKILL_SANDBOX_WORKSPACE_ACCESS=rw
_10
SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST=[]

这些值应以你的实际验证范围为准。例如某个 Skill 在本地调试时必须访问外部网络，就需要显式调整 SKILLFLAW_SKILL_SANDBOX_NETWORK，而不能默认假设沙箱已经具备网络访问能力。

MCP 如何使用沙箱​

MCP 沙箱执行会复用 Skill 沙箱的 OpenSandbox 连接配置，因此本地后端必须能够访问同一个 OpenSandbox 服务。同时，MCP 还需要补充自己的沙箱镜像配置，因为 MCP 会按服务语言选择不同镜像。

本地开发至少应配置以下三类方式之一：

  • 使用共享 MCP 沙箱镜像：SKILLFLAW_MCP_SANDBOX_IMAGE
  • 使用按语言拆分的镜像：SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE、SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE
  • 使用镜像 repository/tag 组合：例如 SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_REPOSITORY 与 SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE_TAG

示例：


_10
SKILLFLAW_MCP_SANDBOX_BASE_DIR=~/.skillflaw/mcp-sandboxes
_10
SKILLFLAW_MCP_SANDBOX_PYTHON_IMAGE=ghcr.io/cwinux/skillflow_mcp_python:v1.0.1
_10
SKILLFLAW_MCP_SANDBOX_TYPESCRIPT_IMAGE=ghcr.io/cwinux/skillflow_mcp_ts:v1.0.1

MCP 沙箱镜像必须填写 Docker 镜像引用，不能填写 HTTP URL。如果你改为分别配置 repository 和 tag，也要保证二者和 OpenSandbox 实际可拉起的运行镜像一致。

沙箱配置要求​

在本地测试 Skill 或 MCP 前，请至少确认以下要求：

  1. OpenSandbox 已完成部署，并且 SkillFlaw 后端可以访问。
  2. .env 中的 OpenSandbox 协议、域名和 API Key 与实际服务一致。
  3. 沙箱镜像与当前要验证的运行语言一致。
  4. CPU、内存、进程数、超时、文件系统和网络限制与本地验证范围匹配。
  5. 任何需要传入 Skill 沙箱的环境变量，都应显式列入 SKILLFLAW_SKILL_SANDBOX_ENV_ALLOWLIST，不要依赖隐式继承。
  6. 如果你修改了沙箱镜像、运行镜像 repository/tag，或 OpenSandbox 的 execd_image，必须先重启沙箱服务再重新测试。

如果这些配置未保持一致，本地联调可能出现与实际产品行为不一致的结果，例如镜像解析失败、运行时启动失败、依赖缺失或沙箱超时。

2. 安装依赖​

推荐直接使用项目封装入口：


_10
make init

该命令会完成：

  • make install_backend
  • make install_frontend
  • uvx pre-commit install

3. 初始化数据库​


_10
make init_db

这个命令会初始化 schema、基础数据以及默认管理员账号。

如果目标数据库尚不存在，make init_db 会先尝试自动创建目标数据库，然后继续执行初始化。

4. 启动开发服务​

建议分别使用多个终端。

后端​


_10
make backend

默认端口为 7860。

前端​


_10
make frontend

默认端口为 3000。

文档站​


_10
make docs docs_port=3001

这会以独立 docs 服务模式启动文档站，并在 3001 端口根路径提供多语言访问。

如果你正在编写文档并需要热更新预览，请使用：


_10
make docs_dev docs_port=3001

5. 常用开发循环​

快速启动打包态应用​


_10
make run_cli

强制前端全量重建后启动​


_10
make run_clic

构建项目​


_10
make build

格式化与检查​


_10
make format
_10
make lint

运行后端单元测试​


_10
make unit_tests

6. 何时改用 Docker​

如果你要验证更接近产品部署的完整服务编排，而不是前后端分离的开发服务，可以使用：


_10
docker compose -f docker/docker-compose.yml up -d

相关文档​