ChainlessChain 文档

主题

启动应用 (start) ​

启动 ChainlessChain 桌面应用程序，支持 GUI 模式和 headless 模式（仅后端服务）。

概述 ​

start 命令用于启动 ChainlessChain 桌面应用，支持 GUI 模式和 headless 模式（仅启动 Docker 后端服务）。启动前会自动检查配置完成状态和应用是否已在运行，可通过 --services 选项同时启动 Docker 后端服务。

核心特性 ​

  • 🔹 桌面启动: 启动 Electron 桌面 GUI 应用
  • 🔹 Headless 模式: 仅启动 Docker 后端服务，不启动 GUI
  • 🔹 服务联动: 可同时启动 Docker 后端服务
  • 🔹 重复检测: 自动检测应用是否已在运行，避免重复启动

系统架构 ​

start 命令 → start.js (Commander) → config-manager + process-manager
                                          │
                    ┌─────────────────────┼──────────────────────┐
                    ▼                     ▼                      ▼
              检查 setup 状态       启动 Docker 服务         启动桌面应用
              (setupCompleted)    (--services/--headless)   (process-manager)
                                          │                      │
                                          ▼                      ▼
                                   docker-compose up -d     Electron 进程
                                                            返回 PID

命令参考 ​

bash
chainlesschain start                # 启动桌面应用
chainlesschain start --headless     # 仅启动后端服务（无 GUI）
chainlesschain start --services     # 启动桌面应用 + Docker 服务

选项说明 ​

选项说明
--headless仅启动 Docker 后端服务，不启动桌面 GUI
--services同时启动 Docker 后端服务

配置参考 ​

bash
# CLI 标志
--headless       # 仅启动 Docker 后端服务，不启动桌面 GUI
--services       # 同时启动 Docker 后端服务

# 配置路径（需 setupCompleted=true 才允许启动）
# Windows: %APPDATA%/chainlesschain-desktop-vue/.chainlesschain/config.json
# macOS:   ~/Library/Application Support/chainlesschain-desktop-vue/.chainlesschain/config.json
# Linux:   ~/.config/chainlesschain-desktop-vue/.chainlesschain/config.json

# PID 文件
<userData>/.chainlesschain/desktop-app.pid    # 运行中进程 ID

性能指标 ​

操作目标实际状态
配置状态检查< 50ms~20ms✅
重复运行检测 (PID)< 100ms~40ms✅
桌面应用冷启动< 5s~3s✅
--headless Docker 启动< 20s~12s✅
--services 联动启动< 25s~15s✅

测试覆盖率 ​

✅ start.test.js  - 覆盖 CLI 主要路径
  ├── 参数解析
  ├── 正常路径
  ├── 错误处理
  └── JSON 输出

关键文件 ​

  • packages/cli/src/commands/start.js — 命令实现
  • packages/cli/src/lib/process-manager.js — 进程管理（启动、检测、PID）
  • packages/cli/src/lib/service-manager.js — Docker 服务管理
  • packages/cli/src/lib/config-manager.js — 配置读取

安全考虑 ​

  • 启动前检查 setupCompleted 状态，未完成配置时拒绝启动
  • --headless 和 --services 模式需要 Docker 可用
  • 桌面应用以用户权限运行，不需要管理员权限
  • 重复启动会被自动检测并跳过

使用示例 ​

场景 1：日常启动桌面应用 ​

bash
chainlesschain start

启动 ChainlessChain 桌面应用。如果应用已在运行，会提示而非重复启动。

场景 2：开发环境完整启动 ​

bash
chainlesschain start --services

同时启动桌面应用和 Docker 后端服务（PostgreSQL、Redis、Ollama、Qdrant），适合开发调试。

场景 3：服务器 headless 部署 ​

bash
chainlesschain start --headless

仅启动 Docker 后端服务，不启动 GUI。适用于服务器、容器化环境或远程开发。

故障排查 ​

问题解决方案
Setup not completed先运行 chainlesschain setup 完成配置
Docker is required安装 Docker Desktop（--headless 和 --services 需要）
docker-compose.yml not found在项目根目录下运行，或确认 backend/docker 目录存在
应用启动后无窗口检查 Electron 二进制是否已下载：chainlesschain update
already running应用已在运行，无需重复启动

相关文档 ​

基于 MIT 许可发布

Copyright © 2024-2026 ChainlessChain Team