跳到主要内容

安装 SkillFlaw - Python

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

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

  • docker/docker-compose-py.yml
  • make init
  • make init_db
  • make backend
  • make run_cli / make run_clic

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

适合选择 Python 版本的场景​

  • 你要使用仓库当前的 Python backend 工作流
  • 你需要 README_PY.md 中对应的源码开发链路
  • 你要使用带 backend_py 的 Python Docker Compose 栈
  • 你需要 make run_cli 这一套 Python 本地验证方式

使用 Docker Compose 安装​

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

前置条件​

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

操作步骤​

  1. clone 仓库：


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

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


    _10
    cp .env.example .env

  3. 启动 Python 栈：


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

这条 Python Compose 链路会启动 frontend、backend_py、doc、redis、pgsql，以及一次性的 secret_init 初始化服务。

默认访问地址​

  • frontend：http://localhost:3001
  • backend 健康检查：http://localhost:7860/health
  • docs：http://localhost:3002

安装成功判定​

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

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

从源码安装​

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

源码安装前提​

  • Python >=3.10,<3.14（推荐 3.12）
  • uv >=0.4
  • Node.js 22 LTS 与 npm >=10.9
  • PostgreSQL
  • Redis（仅当 SKILLFLAW_CACHE_TYPE=redis 时）
  • SKILLFLAW_SECRET_KEY_FILE

操作步骤​

  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_DATABASE_URL
    • SKILLFLAW_SECRET_KEY_FILE

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

    • SKILLFLAW_CACHE_TYPE=redis
    • SKILLFLAW_REDIS_HOST
    • SKILLFLAW_REDIS_PORT

  4. 安装依赖：


    _10
    make init

  5. 初始化数据库：


    _10
    make init_db

  6. 启动 backend：


    _10
    make backend

  7. 启动 frontend：


    _10
    make frontend

可选的正式发布形态本地验证：


_10
make run_cli
_10
make run_clic

安装成功判定​

  • 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 能正常打开应用入口

可选运行时依赖​

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

OpenSandbox​

当 Python 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

在容器化路径下，务必保证这些地址对 backend_py 容器内部可达。

OpenCode​

  • Python 源码路径要求 opencode 可在运行 make backend 的宿主机环境中直接调用
  • Python Docker 路径使用 docker/backend/Dockerfile，镜像已内置 opencode
  • SKILLFLAW_CONTAINER_OPENCODE_* 仅用于容器化 Python backend 路径

默认管理员账号​

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

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

推荐继续阅读​