跳到主要内容

安装 SkillFlaw

SkillFlaw 提供两种公开安装路径：

  • Docker Compose：适合验证接近产品部署形态的完整本地产品栈
  • 源码安装：适合参与开发、调试或自定义扩展

克隆代码仓库​

在使用任一安装路径之前，先将仓库 clone 到本地：


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

使用 Docker Compose 安装​

需要同时启动前端、后端、数据库、Redis 与文档站时，推荐使用该方式。

前置条件​

  • 已安装 Docker 与 Docker Compose
  • 默认 Compose 路径不需要你额外准备本地 PostgreSQL 或 Redis
  • 默认 Compose 路径会在首次启动时自动生成并持久化密钥文件，不需要你单独准备 SKILLFLAW_SECRET_KEY_FILE
  • 只有在你希望给 backend 传额外运行时变量或本地覆盖项时，才需要创建 .env

操作步骤​

  1. 如果尚未 clone 仓库，先完成 clone。

    • macOS：


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

    • Linux（Ubuntu / Debian）：


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

  2. 如需补充额外运行时变量或本地覆盖项，可选地将仓库根目录（与 README.md、Makefile 同级）的 .env.example 复制为仓库根目录 .env：

    • macOS：


      _10
      cp .env.example .env

    • Linux（Ubuntu / Debian）：


      _10
      cp .env.example .env

  3. 启动服务：


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

    首次启动时，Docker Compose 会先运行一次性的 secret_init 服务，自动生成高熵 secret key 文件，并持久化到 skillflaw_secret_data volume 中，供 backend 后续复用。

    仓库根目录的 .env（即 skillflaw/.env，与 README.md、Makefile 同级）在这个路径下是可选项；只有当你希望让 backend 读取额外运行时变量或本地覆盖项时才需要创建。

    对于 Docker Compose 路径，除非你明确覆盖默认编排，否则不需要在 .env 中手动填写 SKILLFLAW_SECRET_KEY_FILE、SKILLFLAW_DATABASE_URL、SKILLFLAW_CACHE_TYPE、SKILLFLAW_REDIS_HOST 或 SKILLFLAW_REDIS_PORT。Compose 已将后端接入内置 PostgreSQL 与 Redis，并自动准备默认密钥文件。

  4. 在全新 PostgreSQL 数据卷上，数据库容器会按以下顺序初始化：

    这一步由 Compose 内置 PostgreSQL 容器自动完成，并不是要求你在默认 Compose 工作流下再单独配置一套本地 PostgreSQL 或 Redis。

    1. sql/skillflow.sql
    2. data/postgresql/skillflaw_init_data.sql

  5. 验证默认访问地址：

    • 前端：http://localhost:3001
    • 后端健康检查：http://localhost:7860/health
    • 文档：http://localhost:3002

该 Compose 栈默认启动 frontend、backend、doc、redis、pgsql 五个服务，以及一次性的 secret_init 初始化服务。backend 通过持久化的 skillflaw_secret_data volume 读取 /run/secrets/skillflaw_secret_key。

安装成功判定​

满足以下条件即可视为 Docker Compose 安装成功：

  • docker compose -f docker/docker-compose.yml ps 显示 pgsql、redis、backend、frontend、doc 处于运行状态，且 secret_init 已成功执行完成
  • http://localhost:7860/health 返回健康状态
  • http://localhost:3001 能正常打开 SkillFlaw 前端
  • http://localhost:3002 能正常打开独立 docs 站点
  • 可以使用下方默认管理员账号登录

常见问题​

默认 Docker Compose 路径需要 .env 吗？​

不需要。默认 Compose 工作流下，.env 是可选项。只有当你希望覆盖 backend 读取的运行时变量时，才需要创建它。文件位置是仓库根目录下的 skillflaw/.env，不是 docker/.env。

使用 Docker Compose 时还需要执行 make init_db 吗？​

不需要。make init_db 是源码安装路径的数据库初始化入口。默认 Compose 工作流下，pgsql 容器会在全新 PostgreSQL 数据卷上自动执行 sql/skillflow.sql 与 data/postgresql/skillflaw_init_data.sql。

为什么 docker compose ps 里会看到 secret_init 已退出？​

这是预期行为。secret_init 是一次性的初始化服务，只在首次启动时负责在 skillflaw_secret_data 中生成默认密钥文件。它成功执行后保持退出状态，不需要长期运行。

安装与部署 docs 服务​

SkillFlaw 文档站以独立 Docusaurus 站点发布。 部署时应使用独立端口、容器或域名，并保持站点挂载在根路径 /。

Docs 服务​

请根据目标选择合适的 docs 工作流：

  • make docs_dev：以热更新方式启动 Docusaurus 开发服务器，适合编写文档
  • make docs_build：生成位于 docs/build 的根路径静态产物
  • make docs_serve：重新构建独立文档产物并立即启动本地静态服务
  • make docs_start_only：直接启动已有文档产物，不在启动前重新构建

如需热更新预览，请在仓库根目录执行：


_10
make docs_dev docs_port=3001

如需生成部署用静态产物，请执行：


_10
make docs_build

该命令会将根路径静态资源输出到 docs/build，可直接用于独立 docs 服务托管。

如需在启动前按当前源码重新构建独立文档站，请执行：


_10
make docs_serve docs_port=3001

该命令会重新构建独立文档产物，并在所选端口启动静态服务。以 docs_port=3001 为例，默认入口为 http://localhost:3001/，中文首页为 http://localhost:3001/zh-CN。

如已有可用文档产物，仅需启动 docs 服务而不重建时，请执行：


_10
make docs_start_only docs_port=3001 docs_start_dir=build

可通过 docs_start_dir 指定已有产物目录。例如，执行 make docs_build 后，目录为 docs/build。

当文档以独立域名发布时，应让该域名直接指向 docs 服务，并保持站点挂载在根路径 /。

关于独立 docs 服务的完整工作流与命令说明，请继续阅读 构建与启动文档站点。

默认管理员账号​

仓库初始化 SQL 执行完成后，默认管理员账号为：

  • 用户名：admin
  • 密码：Skillflaw@123321

更多说明见：用于部署的 SkillFlaw 安装说明

Python 包分发状态​

SkillFlaw 当前未提供可通过 uv pip install skillflaw 直接安装的公开 PyPI 包。

如果你现在需要可运行环境，请使用以下路径之一：

  • Docker Compose：适合启动完整本地产品栈；
  • 源码安装：适合基于当前仓库运行、调试或开发。

从源码安装​

需要参与仓库开发、修改前端、修改文档或调试后端时，推荐使用源码方式。

源码安装前提​

  • 操作系统：macOS 或 Linux；Windows 用户优先使用 WSL2 或 Dev Container
  • Git：稳定版本即可
  • make：可直接在 PATH 中调用
  • Python：推荐 3.12，官方支持范围 >=3.10,<3.14
  • uv：>=0.4
  • Node.js：推荐 22 LTS
  • npm：>=10.9
  • PostgreSQL：必需，推荐 16，最低兼容 14
  • Redis：仅当 SKILLFLAW_CACHE_TYPE=redis 时必需，推荐 7，最低兼容 6
  • 当你需要本地 docs 工作流时，再准备 yarn 1.22.x

源码安装路径下必须准备真实的密钥文件：

  • 通过 SKILLFLAW_SECRET_KEY_FILE 提供
  • 文件内容必须是一行高熵随机字符串
  • 文件应放在仓库外部
  • 不要提交到版本控制系统

当前前端包允许 node >=20.19.0，但仓库文档与 docs 工具链统一在 Node.js 22 LTS。若希望前端与 docs 体验一致，建议使用 Node.js 22 LTS。

macOS 下安装命令示例​


_16
# 安装 Homebrew（如未安装）
_16
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
_16
_16
# 安装 Git、make、Python、uv、Node.js、PostgreSQL、Redis
_16
brew install git make python@3.12 uv node@22 postgresql@16 redis
_16
_16
# 安装 npm（随 node@22 一起安装）
_16
# 检查版本
_16
git --version
_16
make --version
_16
python3 --version
_16
uv --version
_16
node --version
_16
npm --version
_16
psql --version
_16
redis-server --version

Linux（Ubuntu/Debian）下安装命令示例​


_36
# 更新包管理器
_36
sudo apt update
_36
_36
# 安装基础依赖
_36
sudo apt install -y git make python3 python3-venv python3-pip curl build-essential ca-certificates gnupg lsb-release
_36
_36
# 安装 uv（使用官方安装脚本）
_36
curl -LsSf https://astral.sh/uv/install.sh | sh
_36
export PATH="$HOME/.local/bin:$PATH"
_36
_36
# 安装 Node.js 22 LTS（使用 NodeSource 官方脚本）
_36
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
_36
sudo apt install -y nodejs
_36
_36
# 安装 PostgreSQL 16（使用 PostgreSQL 官方 PGDG 仓库）
_36
sudo install -d /usr/share/postgresql-common/pgdg
_36
sudo curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc -o /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
_36
sudo sh -c 'echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt $(. /etc/os-release && echo $VERSION_CODENAME)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
_36
sudo apt update
_36
sudo apt install -y postgresql-16
_36
_36
# 安装 Redis 7（使用 Redis 官方仓库）
_36
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
_36
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(. /etc/os-release && echo $VERSION_CODENAME) main" | sudo tee /etc/apt/sources.list.d/redis.list > /dev/null
_36
sudo apt update
_36
sudo apt install -y redis
_36
_36
# 检查版本
_36
git --version
_36
make --version
_36
python3 --version
_36
uv --version
_36
node --version
_36
npm --version
_36
psql --version
_36
redis-server --version

操作步骤​

  1. 如果尚未 clone 仓库，先完成 clone。

    • macOS：


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

    • Linux（Ubuntu / Debian）：


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

  2. 先确认本地工具链已准备好：

    • Python >=3.10,<3.14（推荐 3.12）

    • uv >=0.4

    • Node.js 22 LTS 与 npm >=10.9

    • make

    • macOS：


      _10
      python3 --version
      _10
      uv --version
      _10
      node --version
      _10
      npm --version
      _10
      make --version

    • Linux（Ubuntu / Debian）：


      _10
      python3 --version
      _10
      uv --version
      _10
      node --version
      _10
      npm --version
      _10
      make --version

  3. 将 .env.example 复制为 .env。

    • macOS：


      _10
      cp .env.example .env

    • Linux（Ubuntu / Debian）：


      _10
      cp .env.example .env

  4. 至少配置以下变量：

    • SKILLFLAW_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE

    如果你希望使用 Redis 缓存，还需要配置：

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

    为提高源码安装成功率，建议将 SKILLFLAW_DATABASE_URL 指向可访问的 PostgreSQL 16 实例；若启用 Redis 缓存，建议使用可访问的 Redis 7 实例。PostgreSQL 14、Redis 6 在部分环境中可能可用，但不是当前正式文档基线版本。

    • macOS：


      _10
      cat >> .env <<EOF
      _10
      SKILLFLAW_SECRET_KEY_FILE=$HOME/.skillflaw/secret_key
      _10
      SKILLFLAW_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
      _10
      SKILLFLAW_CACHE_TYPE=redis
      _10
      SKILLFLAW_REDIS_HOST=<redis_host>
      _10
      SKILLFLAW_REDIS_PORT=<redis_port>
      _10
      EOF

    • Linux（Ubuntu / Debian）：


      _10
      cat >> .env <<EOF
      _10
      SKILLFLAW_SECRET_KEY_FILE=$HOME/.skillflaw/secret_key
      _10
      SKILLFLAW_DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<database>
      _10
      SKILLFLAW_CACHE_TYPE=redis
      _10
      SKILLFLAW_REDIS_HOST=<redis_host>
      _10
      SKILLFLAW_REDIS_PORT=<redis_port>
      _10
      EOF

  5. 安装依赖：

    • macOS：


      _10
      make init

    • Linux（Ubuntu / Debian）：


      _10
      make init

  6. 初始化数据库：

    • macOS：


      _10
      make init_db

    • Linux（Ubuntu / Debian）：


      _10
      make init_db

    make init 负责安装依赖并准备环境；make init_db 会在需要时自动创建目标 PostgreSQL 数据库、执行 schema、导入初始化数据，并准备默认管理员账号。

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

    若 SKILLFLAW_SECRET_KEY_FILE 对应文件不存在，且当前命令在交互式终端执行，make init_db 会提示要求、可交互生成文件，并将最终路径回写到 .env。

  7. 根据目标选择启动方式：

    开发模式

    • macOS：

      终端 A：


      _10
      make backend

      终端 B：


      _10
      make frontend

    • Linux（Ubuntu / Debian）：

      终端 A：


      _10
      make backend

      终端 B：


      _10
      make frontend

    make frontend 启动的是前端开发服务器。默认本地开发访问入口为：

    • 前端：http://localhost:3000
    • 后端健康检查：http://localhost:7860/health

    正式发布形态本地验证

    若你需要在源码安装路径下验证接近正式发布环境的运行方式，请在仓库根目录执行：

    • macOS：


      _10
      make run_cli

      如需先清理前端构建缓存再完整重建，可执行：


      _10
      make run_clic

    • Linux（Ubuntu / Debian）：


      _10
      make run_cli

      如需先清理前端构建缓存再完整重建，可执行：


      _10
      make run_clic

    在该模式下，SkillFlaw 会先构建前端静态资源，再由后端统一提供应用入口。默认访问地址为：

    • 应用入口：http://localhost:7860

    若你要验证更完整的产品级部署链路，仍建议优先使用 Docker Compose 安装路径。

  8. 若你正在修改文档，再启动 docs：

    • macOS：


      _10
      make docs_dev
      _10
      # or
      _10
      make docs_build
      _10
      # or
      _10
      make docs_serve docs_port=3001
      _10
      # or
      _10
      make docs_start_only docs_port=3001 docs_start_dir=build

    • Linux（Ubuntu / Debian）：


      _10
      make docs_dev
      _10
      # or
      _10
      make docs_build
      _10
      # or
      _10
      make docs_serve docs_port=3001
      _10
      # or
      _10
      make docs_start_only docs_port=3001 docs_start_dir=build

安装成功判定​

满足以下条件即可视为源码安装成功：

  • make init 成功完成，且没有依赖安装错误
  • make init_db 成功完成，并完成默认管理员初始化
  • 执行 make backend 后，http://localhost:7860/health 返回健康状态
  • 使用开发模式时，执行 make frontend 后，http://localhost:3000 能正常打开前端页面
  • 使用正式发布形态本地验证模式时，执行 make run_cli 或 make run_clic 后，http://localhost:7860 能正常打开应用入口
  • 可以使用下方默认管理员账号登录

如需了解更完整的部署初始化流程、导出初始化数据规则与 Compose 行为，请阅读用于部署的 SkillFlaw 安装说明。

Skill 执行相关的可选运行时依赖​

OpenSandbox 与 OpenCode 不是基础前后端产品栈启动的必备前置条件。仅在使用 Skill 沙箱执行或依赖它们的 AI 辅助能力时才需要准备：

  • OpenSandbox：SkillFlaw 默认使用的 Skill 沙箱后端。
  • OpenCode：当需要使用依赖 opencode 的 AI 辅助能力时，必须部署在 SkillFlaw 后端所在服务器可直接调用的环境中。

OpenSandbox 前置要求​

OpenSandbox 可以采用以下任一种方式：

  • 自建 OpenSandbox 服务；
  • 使用 SaaS 形式的 OpenSandbox 服务。

无论采用哪种方式，SkillFlaw 后端都必须可访问该服务。SkillFlaw 通过以下 .env 配置接入 OpenSandbox：

  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_API_KEY
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_PROTOCOL
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_USE_SERVER_PROXY
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_REQUEST_TIMEOUT_SECONDS

当你还需要显式对齐 Skill 运行镜像时，也应同时检查：

  • SKILLFLAW_SKILL_SANDBOX_PYTHON_IMAGE
  • SKILLFLAW_SKILL_SANDBOX_TYPESCRIPT_IMAGE

容器化安装​

  • 仓库根目录的 .env 会被 backend 容器读取，因此 OpenSandbox 访问配置必须写在 skillflaw/.env 中。
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN 必须填写 backend 容器内部可访问 的地址。
  • 如果 OpenSandbox 跑在宿主机上，Docker Desktop 环境通常应使用 host.docker.internal:8080 这类容器可访问地址，而不是 localhost:8080。
  • 如果 OpenSandbox 作为同网段容器或远端服务提供，应填写对应服务名、可路由 IP 或域名。

示例：


_10
SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN=host.docker.internal: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

从源码安装​

  • backend 直接运行在宿主机上时，可继续在仓库根目录 .env 中使用宿主机可访问的 OpenSandbox 地址。
  • 如果 OpenSandbox 也运行在同一台宿主机上，常见配置是 localhost:8080。
  • 如果 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 启动​

  • 如果你使用的是自建 OpenSandbox，而不是 SaaS 端点，必须先启动 OpenSandbox 服务，再启动 SkillFlaw。
  • 当前仓库内的脚本与说明明确使用 opensandbox-server 作为服务进程名；自建服务至少应能以该命令启动。
  • 如果你修改了 OpenSandbox 的 ~/.sandbox.toml、execd_image 或运行镜像配置，需要重启 opensandbox-server 使新配置生效。

_10
opensandbox-server

SkillFlaw 中的 OpenSandbox 使用规范​

  • 保证 SkillFlaw 后端到 OpenSandbox 服务的网络连通性。
  • 在测试或运行 Skill 之前，先完成 Skill 沙箱连接参数配置。
  • 按 Skill 的语言与执行需求配置沙箱镜像和资源限制。
  • 如果你修改了 OpenSandbox 的运行镜像或 execd_image，需要重启 OpenSandbox 服务后新配置才会生效。

OpenCode 前置要求​

SkillFlaw 会在后端所在环境中直接调用 opencode run --pure --format json。因此，OpenCode 必须安装在与 SkillFlaw 后端相同的运行环境中，并确保在启用 AI 辅助 Skill、Flow 或组件能力前，opencode 可通过 PATH 直接解析。

容器化安装​

  • 当前 Docker Compose 路径会用仓库内的 docker/backend/Dockerfile 本地构建 backend 镜像；该镜像已内置 opencode。
  • docker/docker-compose.yml 里的 backend 会按需读取仓库根目录 .env；这也是 SKILLFLAW_CONTAINER_OPENCODE_* 的唯一预期使用场景。
  • backend 容器启动时，会读取仓库根目录 .env 中的 SKILLFLAW_CONTAINER_OPENCODE_* 变量，并自动生成容器内 OpenCode 运行时配置。
  • 这组变量仅用于容器内 backend 的 OpenCode 运行时配置；不是 SkillFlaw 后端对外发起 API 调用的参数。
  • 只要设置了任意 SKILLFLAW_CONTAINER_OPENCODE_* 衍生项，就必须同时设置 SKILLFLAW_CONTAINER_OPENCODE_MODEL；其格式固定为 provider/model。
  • 若你使用自定义 provider，通常还需要同时设置 SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_ID、SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_NAME、SKILLFLAW_CONTAINER_OPENCODE_PROVIDER_NPM、SKILLFLAW_CONTAINER_OPENCODE_API_KEY。
  • SkillFlaw 会从 src/lfx/src 调用 opencode，以命中该目录下为 LFX 准备的本地 AGENTS / opencode.json 规则链路。

从源码安装​

  • opencode 必须安装在运行 make backend 的宿主机环境中，并且在该 shell 的 PATH 内可直接调用。
  • 在启动 SkillFlaw 前，先为 OpenCode 配好 LLM 服务商、目标模型与对应 API Key。
  • 从源码安装时，不应使用 SKILLFLAW_CONTAINER_OPENCODE_* 这组变量；应直接按 OpenCode 自身支持的宿主机配置方式完成模型与凭据配置。

SkillFlaw 中的 OpenCode 使用规范​

  • 在启用 AI 辅助能力前，先完成 OpenCode 的模型与服务商配置。
  • 保持 OpenCode 可用于非交互式 CLI 调用，因为 SkillFlaw 会执行 opencode run --pure --format json 并要求返回可机器解析的结果。
  • 让 SkillFlaw 与 OpenCode 运行在同一后端环境中，避免权限、模型配置或网络策略不一致。
  • 如果你需要在基于仓库的开发流程中手动调试 OpenCode 提示词，优先复用项目根目录下的 AGENTS.md 规则，并在长提示词或参考材料场景下优先使用文件方式传入上下文。

SkillFlaw 当前没有专门的 OpenCode 连接型 .env 配置键，因此服务商、模型与 Key 应按 OpenCode 自身支持的配置方式写入其运行环境。

推荐继续阅读​