C4A Server CLI

@c4a/server-cli — C4A 服务端管理工具，负责服务配置、安装、运维和数据管理。

安装后通过 c4a-server 命令使用，开发阶段可通过 ./start.sh link 全局链接。

工作区

所有命令（除 init 和 version）需在工作区目录下执行。工作区由 c4a-server init 创建，结构如下：

workspace/
├── server.yaml              # 服务配置（权限 0o600）
├── data/
│   ├── c4a.db               # SQLite 数据库（如使用）
│   ├── lancedb/             # LanceDB 向量存储
│   └── logs/                # API 服务日志
├── docker/                  # Docker Compose 文件
├── models/embedding/        # Embedding 模型缓存
├── backups/                 # 数据备份
└── logs/                    # Server 进程日志 + PID 文件

可通过 -c <path> 指定工作区路径，例如：c4a-server -c ~/my-workspace start。

命令一览

初始化

c4a-server init             # 初始化工作区，生成 server.yaml 和目录结构
c4a-server version          # 打印版本号

服务运维

c4a-server status           # 查看所有服务状态（Docker、数据库、API 等）
c4a-server start            # 启动服务（Docker 容器 + API 进程）
c4a-server stop             # 停止服务（API 进程 + Docker 容器）
c4a-server stop-api         # 仅停止 API 进程（不停 Docker 服务）
c4a-server uninstall        # 移除所有 Docker 容器、网络和卷（破坏性）
c4a-server logs [service]   # 查看日志，可指定服务名（mongodb/neo4j/qdrant/milvus）
c4a-server dev-deps         # 确保 Docker 依赖运行（dev 模式内部使用）

数据管理

c4a-server backup [options]                  # 备份数据
c4a-server restore [options]                 # 从备份还原数据
c4a-server purge [options]                   # 清除全部数据（不可逆）

backup 选项：

| 选项 | 说明 | |------|------| | -d, --dir <path> | 备份目录路径，相对于工作区（默认 ./backups） |

restore 选项：

| 选项 | 说明 | |------|------| | -d, --dir <path> | 备份目录路径（默认 ./backups） | | -b, --backup <name> | 指定还原的备份目录名 | | -y, --yes | 跳过确认提示 |

purge 选项：

| 选项 | 说明 | |------|------| | -y, --yes | 跳过确认提示 | | --confirm <text> | 确认文本，必须为 DELETE |

非交互模式示例：c4a-server purge -y --confirm DELETE

交互式菜单（TUI）

无参数运行 c4a-server 进入交互式菜单。

服务设置 →
  ├─ 文档数据库        SQLite / MongoDB
  ├─ 图数据库          Neo4j / NebulaGraph / DuckDB
  ├─ 向量数据库        Qdrant / Milvus / LanceDB
  ├─ LLM 服务         OpenAI / Anthropic / Google
  ├─ Embedding 服务   HuggingFace / Xenova / OpenAI / Google
  ├─ Git 令牌          Git Host 访问凭证（用于远程仓库导入）
  ├─ 接入设置          Host / Port
  └─ 修复配置          补全缺失配置项（使用默认值填充）
服务安装               检测环境并启动 Docker 容器
服务运维 →
  ├─ 状态
  ├─ 启动
  ├─ 停止
  ├─ 卸载
  ├─ 日志
  ├─ LLM 测试         与 LLM 对话测试
  ├─ Embedding 测试   测试 Embedding 服务
  ├─ 测试账户-开启     启用 SuperTest 测试账号
  └─ 测试账户-关闭     冻结 SuperTest 测试账号
数据运维 →
  ├─ 清除全部数据
  ├─ 数据备份
  └─ 数据还原
退出

操作：↑↓ 选择，→← 展开/收起子菜单，空格/回车执行，q 退出。菜单会记住上次选择位置。

服务设置交互流程

从菜单进入各设置项后，会引导选择 provider 并配置连接参数：

• 文档数据库：SQLite（文件路径）/ MongoDB（URI + 数据库名）
• 图数据库：Neo4j（Bolt URI + 认证）/ NebulaGraph（地址 + Space + 认证）/ DuckDB（文件路径，嵌入式，无需 Docker）
• 向量数据库：LanceDB（目录路径）/ Qdrant（URL + API Key）/ Milvus（gRPC 地址）
• LLM：OpenAI / Anthropic / Google（API Key + 可选 Base URL + 默认模型）
• Embedding：HuggingFace / Xenova（模型选择 + 量化精度 q8/q4/fp16/fp32）/ OpenAI / Google（API Key + 模型）
• Git 令牌：添加/修改/删除 Git Host 凭证（host、平台类型、认证用户名、PAT）
• 接入设置：Server 监听地址（host）和端口（port）

配置写入 server.yaml，格式参见下方配置说明。

服务安装交互流程

从菜单选择"服务安装"后，依次执行：

1. Docker Engine 检测
2. 各数据库 provider 连通性检查
3. LLM / Embedding provider 验证
4. Embedding 模型下载与缓存
5. Docker Compose 文件生成
6. 容器启动

配置（server.yaml）

server:
  port: 5100
  host: "::"

doc_db:
  provider: sqlite | mongodb
  sqlite:
    path: ./data/c4a.db
  mongodb:
    uri: mongodb://localhost:27017/c4a?directConnection=true
    database: c4a

graph_db:
  provider: neo4j | nebulagraph | duckdb
  neo4j:
    uri: bolt://localhost:7687
    username: neo4j
    password: ""
  nebulagraph:
    uri: localhost:9669
    username: root
    password: nebula
    space: c4a
  duckdb:
    path: ./data/c4a-graph.duckdb

vector_db:
  provider: lancedb | qdrant | milvus
  collection_prefix: c4a_
  lancedb:
    path: ./data/lancedb
  qdrant:
    url: http://localhost:6333
    api_key: ""
  milvus:
    address: localhost:19530

llm:
  provider: openai | anthropic | google
  openai:
    api_key: ""
    base_url: ""
    default_model: gpt-5.3-codex
  anthropic:
    api_key: ""
    base_url: ""
    default_model: claude-opus-4-6
  google:
    api_key: ""
    base_url: ""
    default_model: gemini-3-pro-preview

embedding:
  provider: huggingface | xenova | openai | google
  huggingface:
    model_id: Xenova/all-MiniLM-L6-v2
    dtype: q8
    cache_dir: ./models/embedding
  xenova:
    model_id: Xenova/bge-m3
    dtype: q8
    cache_dir: ./models/embedding
  openai:
    api_key: ""
    base_url: ""
    model_id: text-embedding-3-small
  google:
    api_key: ""
    model_id: text-embedding-004

git_hosts:
  - host: github.com           # Git 主机域名
    platform: github            # 平台类型：github | gitlab | gitea
    token: ghp_xxx              # Personal Access Token（可选，影响 API 配额）
  - host: code.example.com
    platform: gitlab
    auth_user: oauth2           # 认证用户名（默认 oauth2）
    token: glpat-xxx

auth:
  jwt_secret: ""                # JWT 签名密钥（init 时自动生成）
  access_token_ttl: 24h         # Token 有效期
  allow_test_account: false     # 是否开启测试账号（开发调试用）
  providers: []                 # OAuth/OIDC 登录 provider 列表

git_hosts 说明

git_hosts 配置 Git 仓库的访问凭证，用于远程仓库导入功能。

| 字段 | 必填 | 说明 | |------|------|------| | host | 是 | Git 主机域名（如 github.com、gitlab.com） | | platform | 是 | 平台类型：github / gitlab / gitea | | auth_user | 否 | 认证用户名，默认 oauth2 | | token | 否 | Personal Access Token | | api_base | 否 | 自定义 API 地址（自建实例使用） |

导入模式与 token 的关系：

• API 快速导入：目前仅 github 平台支持。无 token 时也可用（公开仓库），但 GitHub API 未认证请求限额仅 60 次/小时，配置 token 后提升至 5000 次/小时。导入中大型仓库建议配置 token
• 传统克隆导入：所有平台均支持。私有仓库需要 token

各平台 Token 申请方式：

| 平台 | 申请路径 | 最小权限 | 说明 | |------|---------|---------|------| | GitHub | Settings → Developer settings → Personal access tokens | public_repo（Classic）或 Contents: Read-only（Fine-grained） | 推荐 Classic token（勾选 public_repo scope），对所有公开仓库生效。Fine-grained token 仅对授权范围内的仓库生效，未授权仓库（即使公开）会返回 403 | | GitLab | Preferences → Access Tokens → Add new token | read_repository + read_api | 自建 GitLab 同理，在实例的个人设置中创建 | | Gitea | Settings → Applications → Generate New Token | read:repository | 自建 Gitea 同理 |

Classic token（推荐）：勾选 public_repo scope 即可访问所有公开仓库，操作简单。私有仓库需勾选完整 repo scope。

Fine-grained token：可限定到具体仓库，安全性更好，但仅对授权范围内的仓库生效。访问未授权的公开仓库会被 GitHub 返回 403。如需访问多个组织的仓库，需为每个组织分别创建 token。

Token 仅存储在本地 server.yaml 中（文件权限 0o600），不会上传到任何外部服务。

环境变量

| 变量 | 说明 | |------|------| | C4A_CONTAINER_PREFIX | Docker 容器名前缀，用于多实例隔离（默认 c4a） | | C4A_ASSUME_YES=1 | 跳过所有确认提示，适合 CI 和非交互环境 |