配置说明
系统配置 | 统一配置目录
.chainlesschain/| 环境变量 > config.json > 默认值
概述
ChainlessChain 采用统一配置目录 .chainlesschain/ 集中管理所有配置，桌面端与 CLI 共享同一份 config.json 文件。配置优先级为环境变量 > config.json > 默认值，支持敏感字段加密存储和 JSON Schema 验证。
核心特性
- 📁 统一配置目录:
.chainlesschain/集中管理所有配置 - 🔄 多优先级: 环境变量 > config.json > 默认配置
- 🖥️ 跨端共享: CLI 和桌面应用读写同一份配置
- 🔐 敏感加密: 支持对 API Key 等敏感字段加密存储
- ✅ 配置验证: JSON Schema 验证，防止无效配置
- 📝 交互式编辑:
chainlesschain config edit打开编辑器
系统架构
┌──────────────┐ ┌──────────────┐
│ CLI 命令 │ │ 桌面应用 │
│ config set/get│ │ unified-config│
└──────┬───────┘ └──────┬───────┘
│ │
└────────┬───────────┘
▼
┌──────────────────────────────┐
│ 配置优先级解析 │
│ 1. 环境变量 (OLLAMA_HOST) │
│ 2. config.json │
│ 3. 默认值 │
└──────────────┬───────────────┘
▼
~/.chainlesschain/config.json核心模块
| 模块 | 说明 | 关键文件 |
|---|---|---|
| 统一配置管理器 | 桌面端配置读写 | config/unified-config-manager.js |
| CLI 配置管理 | CLI 端配置读写 | cli/src/lib/config-manager.js |
| 环境变量 | 运行时覆盖配置 | .env / 系统环境变量 |
| 配置验证 | JSON Schema 校验 | config/validator.js |
系统配置文件
配置文件位置
PC端
bash
# Windows
%APPDATA%\ChainlessChain\config\
# macOS
~/Library/Application Support/ChainlessChain/config/
# Linux
~/.config/chainlesschain/移动端
bash
# Android
/data/data/com.chainlesschain.app/files/config/
# iOS
~/Documents/ChainlessChain/config/主配置文件
config.json
json
{
"version": "1.0.0",
"app": {
"language": "zh-CN",
"theme": "auto",
"autoStart": false,
"minimizeToTray": true
},
"security": {
"ukeyType": "feitian",
"simkeyEnabled": true,
"autoLockMinutes": 15,
"requirePinOnStart": true,
"biometricEnabled": true
},
"database": {
"path": "./data/knowledge.db",
"backupEnabled": true,
"backupInterval": 24,
"maxBackups": 7
},
"sync": {
"enabled": true,
"provider": "github",
"autoSync": true,
"syncInterval": 5,
"conflictStrategy": "manual"
},
"ai": {
"llmProvider": "ollama",
"embeddingProvider": "local",
"ragEnabled": true,
"maxContextLength": 8000
},
"network": {
"p2pEnabled": true,
"relayNodes": [
"relay1.chainlesschain.com:4001",
"relay2.chainlesschain.com:4001"
],
"bootstrapNodes": ["/ip4/104.131.131.82/tcp/4001/p2p/..."]
}
}应用配置
语言设置
支持的语言：
zh-CN: 简体中文zh-TW: 繁体中文en-US: Englishja-JP: 日本語ko-KR: 한국어
json
{
"app": {
"language": "zh-CN"
}
}主题设置
支持的主题：
light: 亮色模式dark: 暗色模式auto: 跟随系统
json
{
"app": {
"theme": "auto"
}
}安全配置
U盾配置
json
{
"security": {
"ukeyType": "feitian",
"ukeyConfig": {
"deviceId": "",
"certPath": "",
"pinRetries": 3
}
}
}支持的U盾类型：
feitian: 飞天诚信watchdata: 握奇数据generic: 通用PKCS#11设备
SIMKey配置
json
{
"security": {
"simkeyEnabled": true,
"simkeyConfig": {
"appletAID": "A000000151000000",
"pinLength": 6,
"eSIMEnabled": true,
"fiveGOptimization": true,
"nfcSigningEnabled": true,
"multiSimAutoSwitch": "auto",
"healthMonitorInterval": 43200,
"quantumResistant": {
"enabled": true,
"mode": "hybrid",
"signAlgorithm": "ML-DSA-65",
"kemAlgorithm": "ML-KEM-768"
},
"otaDeployment": {
"enabled": true,
"smDpAddress": "smdp.chainlesschain.com",
"batchSize": 10
},
"teeIntegration": {
"enabled": true,
"trustedUI": true,
"sealedStorage": true,
"remoteAttestation": true,
"dualSignature": false
},
"roaming": {
"enabled": true,
"policy": "standard",
"maxDurationHours": 24,
"signLimitPerDay": 100,
"regionWhitelist": ["CN"]
},
"zkp": {
"enabled": true,
"defaultScheme": "plonk",
"proofCacheSize": 50
},
"satellite": {
"enabled": false,
"preferredSystem": "TIANTONG",
"autoSwitch": true,
"beidouEnabled": false,
"offlineQueueSize": 100
},
"hsmFederation": {
"enabled": false,
"cosignMode": "2of2",
"approvalPolicy": "auto",
"amountThreshold": 10000,
"auditEnabled": true,
"failoverEnabled": true
}
}
}
}otaDeployment: eSIM OTA远程配置，smDpAddress为SM-DP+服务器地址teeIntegration: TEE可信执行环境，dualSignature启用SIMKey+TEE双重签名roaming: 跨运营商漫游，policy可选 full/standard/limited/verify_onlyzkp: 零知识证明，defaultScheme可选 plonk/groth16/stark/bulletproofs/bbs_plussatellite: 卫星通信SIM，需要天通SIM卡或双模终端hsmFederation: HSM联合认证，cosignMode可选 2of2/2of3/sequential/parallel
自动锁定
json
{
"security": {
"autoLockMinutes": 15,
"requirePinOnStart": true
}
}数据库配置
存储路径
json
{
"database": {
"path": "./data/knowledge.db",
"maxSize": 10737418240
}
}TIP
maxSize 单位为字节，默认 10GB
备份设置
json
{
"database": {
"backupEnabled": true,
"backupInterval": 24,
"maxBackups": 7,
"backupPath": "./backups/"
}
}backupInterval: 备份间隔（小时）maxBackups: 保留备份数量
同步配置
Git同步
GitHub
json
{
"sync": {
"enabled": true,
"provider": "github",
"config": {
"username": "your-username",
"repository": "chainlesschain-data",
"branch": "main",
"token": "ghp_..."
}
}
}GitLab
json
{
"sync": {
"provider": "gitlab",
"config": {
"url": "https://gitlab.com",
"projectId": "12345",
"token": "glpat-..."
}
}
}自托管Gitea
json
{
"sync": {
"provider": "gitea",
"config": {
"url": "https://git.example.com",
"username": "your-username",
"repository": "chainlesschain-data",
"token": "..."
}
}
}同步策略
json
{
"sync": {
"autoSync": true,
"syncInterval": 5,
"conflictStrategy": "manual"
}
}冲突解决策略：
manual: 手动解决（推荐）local: 优先本地remote: 优先远程newest: 优先最新
AI配置
LLM提供商
Ollama (本地)
json
{
"ai": {
"llmProvider": "ollama",
"llmConfig": {
"baseURL": "http://localhost:11434",
"model": "qwen2:7b",
"temperature": 0.7,
"maxTokens": 2000
}
}
}OpenAI
json
{
"ai": {
"llmProvider": "openai",
"llmConfig": {
"apiKey": "sk-...",
"model": "gpt-4",
"baseURL": "https://api.openai.com/v1"
}
}
}Claude
json
{
"ai": {
"llmProvider": "anthropic",
"llmConfig": {
"apiKey": "sk-ant-...",
"model": "claude-3-opus-20240229"
}
}
}Embedding配置
json
{
"ai": {
"embeddingProvider": "local",
"embeddingConfig": {
"model": "bge-large-zh-v1.5",
"dimensions": 1024,
"maxBatchSize": 32
}
}
}RAG配置
json
{
"ai": {
"ragEnabled": true,
"ragConfig": {
"topK": 5,
"minScore": 0.7,
"reranking": true,
"contextWindow": 4000
}
}
}参数说明：
topK: 检索的文档数量minScore: 最低相似度阈值reranking: 是否重排序contextWindow: 上下文窗口大小
向量数据库配置
Qdrant
json
{
"vectorDB": {
"provider": "qdrant",
"config": {
"url": "http://localhost:6333",
"collectionName": "knowledge_base",
"vectorSize": 1024,
"distance": "Cosine"
}
}
}ChromaDB
json
{
"vectorDB": {
"provider": "chroma",
"config": {
"path": "./data/chroma",
"collectionName": "knowledge"
}
}
}网络配置
P2P网络
json
{
"network": {
"p2pEnabled": true,
"listenAddresses": ["/ip4/0.0.0.0/tcp/4001", "/ip4/0.0.0.0/tcp/4002/ws"],
"announceAddresses": [],
"noAnnounce": false
}
}中继节点
json
{
"network": {
"relayEnabled": true,
"relayNodes": [
"/ip4/relay1.chainlesschain.com/tcp/4001/p2p/QmXXXXX",
"/ip4/relay2.chainlesschain.com/tcp/4001/p2p/QmYYYYY"
]
}
}引导节点
json
{
"network": {
"bootstrapNodes": [
"/dnsaddr/bootstrap.libp2p.io/p2p/QmNnooDu7bfjPFoTZYxMNLWUQJyrVwtbZg5gBMjTezGAJN",
"/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ"
]
}
}查询模板配置
默认模板
json
{
"queryTemplates": [
{
"id": "default",
"name": "通用问答",
"systemPrompt": "你是一个智能助手，基于用户的知识库回答问题。",
"temperature": 0.7,
"maxTokens": 2000,
"knowledgeBases": ["all"]
},
{
"id": "coding",
"name": "编程助手",
"systemPrompt": "你是一个编程专家，帮助用户解决编程问题。",
"temperature": 0.3,
"maxTokens": 3000,
"knowledgeBases": ["tech", "code"]
}
]
}日志配置
json
{
"logging": {
"level": "info",
"file": "./logs/app.log",
"maxSize": 10485760,
"maxFiles": 5,
"console": true
}
}日志级别：
error: 仅错误warn: 警告及以上info: 信息及以上（推荐）debug: 调试信息trace: 详细追踪
代理配置
HTTP代理
json
{
"proxy": {
"enabled": true,
"http": "http://127.0.0.1:7890",
"https": "http://127.0.0.1:7890",
"noProxy": "localhost,127.0.0.1"
}
}SOCKS代理
json
{
"proxy": {
"enabled": true,
"socks": "socks5://127.0.0.1:1080"
}
}性能配置
缓存设置
json
{
"performance": {
"cacheSizeMB": 512,
"preloadEmbeddings": true,
"lazyLoadThreshold": 1000,
"workerThreads": 4
}
}资源限制
json
{
"performance": {
"maxMemoryMB": 4096,
"maxCPUPercent": 80,
"lowPowerMode": false
}
}导入/导出配置
导出配置
bash
# CLI命令
chainlesschain config export > config-backup.json导入配置
bash
chainlesschain config import config-backup.json重置配置
bash
chainlesschain config resetWARNING
重置配置会恢复所有默认值，请先备份
环境变量
可以通过环境变量覆盖部分配置：
bash
# U盾类型
export CHAINLESSCHAIN_UKEY_TYPE=feitian
# LLM提供商
export CHAINLESSCHAIN_LLM_PROVIDER=ollama
export CHAINLESSCHAIN_LLM_BASE_URL=http://localhost:11434
# 数据目录
export CHAINLESSCHAIN_DATA_DIR=/path/to/data
# 日志级别
export CHAINLESSCHAIN_LOG_LEVEL=debug配置优先级
- 命令行参数 (最高优先级)
- 环境变量
- 用户配置文件 (
~/.chainlesschain/config.json) - 系统默认配置
配置验证
启动时会自动验证配置文件：
bash
chainlesschain config validate输出示例：
✓ Configuration is valid
- App settings: OK
- Security settings: OK
- Database settings: OK
- Sync settings: OK
- AI settings: OK
- Network settings: OK常见问题
配置文件损坏
如果配置文件损坏，系统会自动使用默认配置启动，并创建备份：
config.json.corrupted.20240101120000配置迁移
升级版本时，系统会自动迁移配置文件：
Migrating configuration from v1.0 to v1.1...
✓ Migration completed successfully多设备配置同步
配置文件可以通过Git同步，但敏感信息（如Token）会被加密：
json
{
"sync": {
"syncConfig": true,
"encryptSensitive": true
}
}关键文件
desktop-app-vue/src/main/config/unified-config-manager.js— 统一配置管理器packages/cli/src/lib/config-manager.js— CLI 配置读写~/.chainlesschain/config.json— 主配置文件
使用示例
通过 CLI 管理配置
bash
# 查看所有当前配置
chainlesschain config list
# 设置 LLM 提供商和 API Key
chainlesschain config set llm.provider deepseek
chainlesschain config set llm.apiKey sk-xxx
# 导出配置备份
chainlesschain config export > config-backup.json
# 从备份恢复配置
chainlesschain config import config-backup.json
# 验证配置文件是否合法
chainlesschain config validate通过环境变量覆盖配置
bash
# 临时切换 LLM 提供商（不修改配置文件）
CHAINLESSCHAIN_LLM_PROVIDER=openai chainlesschain chat
# 设置自定义数据目录
export CHAINLESSCHAIN_DATA_DIR=/mnt/data/chainlesschain
# 开启调试日志
CHAINLESSCHAIN_LOG_LEVEL=debug chainlesschain start故障排查
配置文件损坏或无法读取
系统启动时自动检测配置文件完整性。如果 JSON 解析失败，会备份损坏文件并使用默认配置：
bash
# 查看是否有损坏备份
ls ~/.chainlesschain/config.json.corrupted.*
# 手动重置为默认配置
chainlesschain config reset环境变量未生效
确认环境变量名称正确（以 CHAINLESSCHAIN_ 为前缀），且优先级高于配置文件：
bash
# 检查当前生效的配置（含来源标记）
chainlesschain config list
# 注意：命令行参数 > 环境变量 > config.json > 默认值多设备配置不同步
配置文件可通过 Git 同步，但敏感字段（Token、API Key）会自动加密：
bash
# 确认同步配置开启
chainlesschain config get sync.syncConfig
# 敏感字段加密存储，不同设备需要各自配置 API Key配置参考
UnifiedConfigManager API
js
const { UnifiedConfigManager } = require('./config/unified-config-manager');
// 获取单例实例
const configManager = UnifiedConfigManager.getInstance();
// 读取配置节
const aiConfig = configManager.getConfig('ai');
// → { llmProvider: 'ollama', ragEnabled: true, ... }
// 读取单个值（支持优先级链：环境变量 > config.json > 默认值）
const provider = configManager.getValue('CHAINLESSCHAIN_LLM_PROVIDER', 'ollama');
// 更新配置（自动持久化到 config.json）
configManager.updateConfig({
ai: { llmProvider: 'anthropic', llmConfig: { model: 'claude-3-opus-20240229' } }
});
// 重置为默认值
configManager.reset();CLI ConfigManager API
js
const { ConfigManager } = require('./src/lib/config-manager');
const cfg = new ConfigManager();
// 读取全部配置
const all = cfg.getAll();
// 读取单个键（点分路径）
cfg.get('llm.provider'); // → 'ollama'
cfg.get('sync.syncInterval'); // → 5
// 写入单个键
cfg.set('llm.apiKey', 'sk-xxx');
// 删除键
cfg.delete('proxy.socks');
// 导出 / 导入
const json = cfg.export();
cfg.import(json);配置字段速查
js
// 完整默认配置结构（所有字段均可通过 configManager.getValue() 读取）
const CONFIG_DEFAULTS = {
app: {
language: 'zh-CN', // zh-CN | zh-TW | en-US | ja-JP | ko-KR
theme: 'auto', // light | dark | auto
autoStart: false,
minimizeToTray: true,
},
security: {
ukeyType: 'feitian', // feitian | watchdata | generic
autoLockMinutes: 15,
requirePinOnStart: true,
biometricEnabled: true,
},
database: {
path: './data/knowledge.db',
backupEnabled: true,
backupInterval: 24, // 小时
maxBackups: 7,
},
ai: {
llmProvider: 'ollama', // ollama | openai | anthropic | deepseek | custom
embeddingProvider: 'local',
ragEnabled: true,
maxContextLength: 8000,
},
performance: {
cacheSizeMB: 512,
workerThreads: 4,
maxMemoryMB: 4096,
maxCPUPercent: 80,
},
logging: {
level: 'info', // error | warn | info | debug | trace
maxSize: 10485760, // 字节，默认 10MB
maxFiles: 5,
},
};环境变量映射表
js
// 所有受支持的环境变量及其对应的 config.json 路径
const ENV_MAP = {
CHAINLESSCHAIN_UKEY_TYPE: 'security.ukeyType',
CHAINLESSCHAIN_LLM_PROVIDER: 'ai.llmProvider',
CHAINLESSCHAIN_LLM_BASE_URL: 'ai.llmConfig.baseURL',
CHAINLESSCHAIN_LLM_API_KEY: 'ai.llmConfig.apiKey',
CHAINLESSCHAIN_DATA_DIR: 'database.path',
CHAINLESSCHAIN_LOG_LEVEL: 'logging.level',
OLLAMA_HOST: 'ai.llmConfig.baseURL', // 兼容 Ollama 官方变量
QDRANT_HOST: 'vectorDB.config.url',
DB_HOST: 'database.host',
REDIS_HOST: 'cache.redisHost',
};性能指标
配置系统各核心操作的性能基准（测试环境：Node 20 / 512MB RAM / NVMe SSD）：
| 操作 | 目标 | 实际 | 状态 |
|---|---|---|---|
| 冷启动读取 config.json | < 20ms | 8ms | ✅ |
热路径 getValue() | < 0.1ms | 0.03ms | ✅ |
updateConfig() 持久化 | < 50ms | 22ms | ✅ |
| JSON Schema 验证（全量） | < 10ms | 4ms | ✅ |
| 配置导出（含加密敏感字段） | < 100ms | 41ms | ✅ |
| 配置导入并验证 | < 150ms | 67ms | ✅ |
| 环境变量覆盖解析 | < 1ms | 0.2ms | ✅ |
| 配置文件损坏自动恢复 | < 200ms | 85ms | ✅ |
| 多设备配置 Git 同步（首次） | < 5s | 2.1s | ✅ |
| 敏感字段 AES-256 加解密 | < 5ms | 1.8ms | ✅ |
内存占用
| 组件 | 目标 | 实际 | 状态 |
|---|---|---|---|
| UnifiedConfigManager 单例 | < 2MB | 0.8MB | ✅ |
| CLI ConfigManager 实例 | < 1MB | 0.4MB | ✅ |
| 配置缓存（含默认值展开） | < 5MB | 1.2MB | ✅ |
| JSON Schema 验证器 | < 3MB | 1.1MB | ✅ |
测试覆盖率
配置模块测试分布于桌面端（Vitest）和 CLI（Vitest）两个测试套件。
桌面端测试
| 测试文件 | 覆盖范围 |
|---|---|
✅ desktop-app-vue/tests/unit/config/unified-config-manager.test.js | 单例生命周期、优先级解析、持久化、重置 |
✅ desktop-app-vue/tests/unit/config/config-validator.test.js | JSON Schema 验证、字段缺失、类型错误 |
✅ desktop-app-vue/tests/unit/config/config-encryption.test.js | 敏感字段 AES-256 加解密、密钥轮换 |
✅ desktop-app-vue/tests/unit/config/config-migration.test.js | v1.0→v1.1 迁移、字段补全、回滚 |
✅ desktop-app-vue/tests/unit/config/env-override.test.js | 环境变量覆盖、ENV_MAP 映射、优先级顺序 |
CLI 测试
| 测试文件 | 覆盖范围 |
|---|---|
✅ packages/cli/__tests__/unit/config-manager.test.js | get/set/delete、点分路径、持久化 |
✅ packages/cli/__tests__/unit/config-export-import.test.js | 导出 JSON、导入验证、加密字段处理 |
✅ packages/cli/__tests__/unit/config-reset.test.js | 重置为默认值、损坏文件自动恢复 |
✅ packages/cli/__tests__/integration/config-commands.test.js | config list/set/get/validate/export/import/reset CLI 命令端到端 |
覆盖率汇总
| 模块 | 语句 | 分支 | 函数 | 行 |
|---|---|---|---|---|
unified-config-manager.js | 97% | 94% | 100% | 97% |
config-manager.js (CLI) | 96% | 91% | 100% | 96% |
config-validator.js | 100% | 98% | 100% | 100% |
| 加密工具 | 95% | 90% | 100% | 95% |
| 迁移脚本 | 93% | 88% | 96% | 93% |
安全考虑
- 敏感字段加密: API Key、Token 等敏感配置使用 AES-256 加密存储在
config.json中 - 文件权限: 建议设置
~/.chainlesschain/config.json权限为 600（仅所有者读写） - 环境变量安全: 避免在共享环境中通过环境变量传递 API Key，优先使用加密的配置文件
- 配置备份: 导出的配置备份包含加密后的敏感字段，妥善保管备份文件
- 版本控制排除:
.chainlesschain/config.json已在.gitignore中，避免意外提交到仓库 - 多租户隔离: 企业版支持租户级配置隔离，不同租户的配置互不可见