跳到主要内容

安装 SkillFlaw（部署视角）

本文档从部署视角介绍 SkillFlaw 的安装路径，包括 Docker、本地源码运行以及数据库初始化。

交付模式​

  • Docker 安装：通过 docker/docker-compose.yml 运行默认本地交付栈
  • 源码安装：直接从仓库运行产品
  • 开发安装：沿用仓库工作流，其中 make init 负责依赖，make init_db 负责数据库初始化

Docker 安装​

仓库提供 docker/docker-compose.yml，默认会启动以下服务：

  • frontend
  • backend
  • doc
  • redis
  • pgsql

默认交付来源：

  • frontend：ghcr.io/cwinux/skillflaw_frontend:latest
  • doc：ghcr.io/cwinux/skillflaw_docs:latest
  • backend：由仓库内 docker/backend/Dockerfile 本地构建，默认产物名为 skillflaw_backend_local:latest

Docker 前置条件​

  • 已安装 Docker Engine 或 Docker Desktop
  • 已安装 docker compose CLI 插件
  • 默认 Docker 路径不需要你额外准备本地 PostgreSQL、Redis 或 SKILLFLAW_SECRET_KEY_FILE
  • 只有当你希望给 backend 提供额外运行时变量或本地覆盖项时，才需要创建仓库根目录的 .env

启动前请完成：

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

  2. 执行：


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

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

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

    默认 Compose 工作流下，数据库和 Redis 连接已经在 docker/docker-compose.yml 中固定为内置服务，因此通常不需要你在 .env 中再手动填写 SKILLFLAW_SECRET_KEY_FILE、SKILLFLAW_DATABASE_URL、SKILLFLAW_CACHE_TYPE、SKILLFLAW_REDIS_HOST 或 SKILLFLAW_REDIS_PORT，除非你明确要覆盖默认编排。

后端容器会通过持久化的 skillflaw_secret_data volume 在 /run/secrets/skillflaw_secret_key 读取该密钥文件。

在全新 PostgreSQL 数据卷上，数据库容器会按以下顺序执行初始化文件：

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

默认访问点：

  • frontend：http://localhost:3001
  • backend health：http://localhost:7860/health
  • docs：http://localhost:3002

Docker 安装成功判定​

满足以下条件时，可以视为默认 Docker 安装成功：

  • 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 常见问题​

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

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

默认 Docker 路径还需要执行 make init_db 吗？​

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

为什么 secret_init 在启动后显示为已退出？​

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

源码安装​

当你需要直接从仓库运行产品时：

源码安装前置条件​

  • 已准备 SKILLFLAW_DATABASE_URL
  • 已准备 SKILLFLAW_SECRET_KEY_FILE
  • SKILLFLAW_SECRET_KEY_FILE 对应文件内容必须是一行高熵随机字符串，并应放在仓库外、排除在版本控制外
  • PostgreSQL 必需，推荐 16，最低兼容 14
  • 当 SKILLFLAW_CACHE_TYPE=redis 时，Redis 必需，推荐 7，最低兼容 6

如果密钥文件不存在，make init_db 会先说明要求，并可交互式生成该文件。

  1. 将 .env.example 复制为 .env
  2. 配置 SKILLFLAW_DATABASE_URL
  3. 配置 SKILLFLAW_SECRET_KEY_FILE
  4. 执行 make init
  5. 执行 make init_db
  6. 分别执行 make backend 与 make frontend

如果你同时在维护文档，请根据目标选择 docs 工作流，例如 make docs_dev、make docs_build、make docs_serve docs_port=3001 或 make docs_start_only docs_port=3001 docs_start_dir=build。

数据库初始化​

make init 只负责安装依赖，不会初始化数据库。

make init_db 才会执行：

  • 在需要时自动创建目标数据库
  • schema 初始化
  • 导出初始化数据导入
  • 默认管理员账号准备

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

在交互式终端中，如果密钥文件缺失，make init_db 可以自动生成密钥文件，并把最终的 SKILLFLAW_SECRET_KEY_FILE 路径回写到 .env。

导出的初始化数据文件 data/postgresql/skillflaw_init_data.sql 也会保留来源管理员账号信息。

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

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

OpenSandbox 前置要求​

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

容器化安装​

  • backend 容器会读取仓库根目录 .env，因此 OpenSandbox 的访问地址、协议与凭据必须写在 skillflaw/.env 中。
  • SKILLFLAW_SKILL_SANDBOX_OPENSANDBOX_DOMAIN 必须是 backend 容器内部可访问的地址；若 OpenSandbox 跑在宿主机上，不应继续填写 localhost:8080。
  • Docker Desktop 场景下，常见做法是改成 host.docker.internal:8080；若 OpenSandbox 来自同网段容器或远端服务，则改为对应服务名、IP 或域名。

从源码安装​

  • backend 直接运行在宿主机上时，可在仓库根目录 .env 中继续填写宿主机可访问的地址。
  • 如果 OpenSandbox 与 backend 在同一台宿主机上，常见配置是 localhost:8080。

自建 OpenSandbox 启动​

  • 自建 OpenSandbox 需先启动服务，再启动 SkillFlaw。
  • 当前仓库脚本与说明明确使用 opensandbox-server 作为服务进程名；若你修改了 ~/.sandbox.toml 或 execd_image，应重启该服务。

_10
opensandbox-server

OpenCode 前置要求​

SkillFlaw 会直接在后端运行环境中调用 opencode run --pure --format json。

容器化安装​

  • 默认 Compose 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 的宿主机环境中。
  • 在启动 SkillFlaw 前，先完成 OpenCode 的服务商、模型与 API Key 配置。
  • 从源码安装时，不应使用 SKILLFLAW_CONTAINER_OPENCODE_* 这组变量；应直接按 OpenCode 自身支持的宿主机配置方式完成模型与凭据配置。

配置说明​

  • OpenCode 不需要额外守护进程；SkillFlaw 会按请求直接调用 CLI。
  • SkillFlaw 当前没有专门的 OpenCode 连接型 .env 配置键，因此服务商、模型与 Key 应按 OpenCode 自身支持的配置方式写入其运行环境。

默认管理员账号​

默认管理员账号：

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

执行 make init_db 时，会基于当前密钥文件重新生成管理员密码哈希，因此不会直接复用其他环境导出的密码哈希。

初始化数据导出​

如需重新生成初始化 SQL，可执行：


_10
make export_db_init_data

该导出会主动排除运行态或敏感数据表，并对敏感配置字段做清洗。当前规则包括：

  • 排除 sf_job、sf_message、sf_transaction、sf_vertex_build
  • 排除 sf_config、sf_variable、sf_apikey、sf_user_chat_session
  • sf_user 仅保留 admin
  • 敏感 JSON / 配置字段在写出 SQL 前统一脱敏或清空