跳到主要内容

安装 SkillFlaw - TypeScript

本文档说明 SkillFlaw TypeScript backend 运行时 的正式安装路径。

当你的目标运行时基于以下链路时，请使用本页：

  • docker/docker-compose-ts.yml
  • make ts_install_backend
  • make ts_init_db
  • make ts_backend
  • make ts_backend_verify
  • make ts_lfx_build / make ts_lfx_test
  • make ts_tool_build / make ts_tool_test

如果你需要的是 Python backend 运行时，请改用 安装 SkillFlaw - Python。

适合选择 TypeScript 版本的场景​

  • 你要使用仓库当前的 TypeScript backend 工作流
  • 你需要 README_TS.md 中对应的源码开发链路
  • 你要使用带 backend_ts 的 TypeScript Docker Compose 栈
  • 你需要 backend、LFX 或 tool 的 TypeScript 包级校验链路

使用 Docker Compose 安装​

当你需要完整本地产品栈时，推荐使用此路径。

前置条件​

  • 已安装 Docker Engine / Docker Desktop 与 Docker Compose
  • 仓库根目录 .env 是可选项，只有在需要覆盖 TypeScript 栈运行时配置时才需要创建
  • 该路径会通过 SKILLFLAW_TS_DATABASE_URL 使用独立的 TypeScript 数据库

操作步骤​

  1. clone 仓库：


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

  2. 如需覆盖运行时配置，可选地复制 .env.example 为 .env：


    _10
    cp .env.example .env

  3. 启动 TypeScript 栈：


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

首次启动时，这条 Compose 链路会初始化独立的 TypeScript 数据库、在 skillflaw_secret_ts_data 中创建密钥文件、执行 db_init_ts、通过 db_init_export_ts 回写 TypeScript 初始化数据，并最终通过一次性的 stack_check_ts 服务完成 backend、frontend 与 docs 的可达性自检。

默认访问地址​

  • frontend：http://localhost:3003
  • backend 健康检查：http://localhost:7861/health
  • docs：http://localhost:3004

安装成功判定​

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

  • docker compose -f docker/docker-compose-ts.yml ps 显示 pgsql、redis、backend_ts、frontend、doc 处于运行状态，且 secret_init、db_init_ts、db_init_export_ts、stack_check_ts 已成功执行完成
  • docker compose -f docker/docker-compose-ts.yml logs stack_check_ts 末尾出现 [backend_ts] ok、[frontend] ok、[doc] ok
  • http://localhost:7861/health 返回健康状态
  • http://localhost:3003 能正常打开 SkillFlaw 前端
  • http://localhost:3004 能正常打开独立 docs 站点

从源码安装​

如需开发 TypeScript backend、调试仓库代码、定制 frontend 或基于仓库扩展能力，建议采用源码方式。

源码安装前提​

  • Node.js 22 LTS 与 npm >=10.9
  • PostgreSQL
  • SKILLFLAW_TS_DATABASE_URL
  • SKILLFLAW_SECRET_KEY_FILE
  • SKILLFLAW_TS_TEST_DATABASE_URL（仅当需要测试时）

操作步骤​

  1. clone 仓库：


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

  2. 将 .env.example 复制为 .env：


    _10
    cp .env.example .env

  3. 至少配置以下变量：

    • SKILLFLAW_TS_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE
    • SKILLFLAW_TS_TEST_DATABASE_URL（仅当需要测试或包级校验时）

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

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

  4. 安装 TypeScript backend 依赖：


    _10
    make ts_install_backend

  5. 初始化 TypeScript backend 数据库：


    _10
    make ts_init_db

  6. 启动 backend：


    _10
    make ts_backend

  7. 启动 frontend：


    _10
    make frontend

可选的包级校验：


_10
make ts_backend_verify
_10
make ts_lfx_build
_10
make ts_lfx_test
_10
make ts_tool_build
_10
make ts_tool_test

安装成功判定​

  • make ts_install_backend 完成且没有依赖安装错误
  • make ts_init_db 成功完成
  • 执行 make ts_backend 后，http://localhost:7860/health 返回健康状态
  • 执行 make frontend 后，http://localhost:3000 能正常打开前端页面
  • 命中的 TypeScript 校验命令执行通过

可选运行时依赖​

OpenSandbox 与 OpenCode 不是基础平台启动的前置条件，仅在需要 Skill 沙箱执行或 AI 辅助流程时才需要准备。

OpenSandbox​

当 TypeScript backend 需要接入 OpenSandbox 时，请在仓库根目录 .env 中配置：

  • 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

对于仓库本地 TypeScript backend 运行方式，务必保证这些地址对运行 make ts_backend 的宿主机环境可达。

OpenCode​

  • TypeScript 运行时要求 opencode 可在运行 make ts_backend 的宿主机环境中直接调用
  • 本文档中的 TypeScript 路径不使用 SKILLFLAW_CONTAINER_OPENCODE_*
  • TypeScript backend 会从 src/lfx/src 调用 opencode

默认管理员账号​

仓库初始化后默认管理员账号为：

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

推荐继续阅读​