跳到主要内容

用于部署的 SkillFlaw 安装 - Python

本文档说明 SkillFlaw Python backend 运行时 的部署视角安装路径。

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

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

如果你要准备的是 TypeScript 部署，请改用 用于部署的 SkillFlaw 安装 - TypeScript。

交付模式​

  • Docker 安装：通过 docker/docker-compose-py.yml 运行完整本地交付栈
  • 源码安装：直接从仓库运行 Python 产品
  • 开发安装：沿用 Python 仓库工作流，使用 make init、make init_db、make backend 与 make frontend

Docker 安装​

Python 部署路径使用 docker/docker-compose-py.yml，默认会启动以下服务：

  • frontend
  • backend_py
  • doc
  • redis
  • pgsql

Docker 前置条件​

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

操作步骤​

  1. 如需覆盖运行时配置，可选地将 .env.example 复制为 .env。

  2. 启动服务：


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

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

默认访问点​

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

Docker 安装成功判定​

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

  • 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 产品时：

源码安装前置条件​

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

操作步骤​

  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。

如果你需要更接近正式发布形态的本地运行方式，可在仓库根目录执行 make run_cli 或 make run_clic。

数据库初始化​

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

如果 SKILLFLAW_DATABASE_URL 指向的数据库尚不存在，make init_db 会先尝试自动创建该数据库。对应 PostgreSQL 用户必须具备 CREATE DATABASE 权限。

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

OpenSandbox 与 OpenCode 不是基础平台启动的前置条件。

  • 对于 OpenSandbox，请在仓库根目录 .env 中配置相关变量，并确保地址对 Python backend 运行时可达。
  • 对于 OpenCode，Python Docker 镜像已内置 opencode；Python 源码路径则要求 opencode 可在运行 make backend 的宿主机环境中直接调用。
  • SKILLFLAW_CONTAINER_OPENCODE_* 仅用于容器化 Python backend 路径。

默认管理员账号​

默认管理员账号：

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

初始化数据导出​

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


_10
make export_db_init_data

推荐继续阅读​