环境配置详解
LingFlow 通过环境变量与 .env 文件完成全部配置。本页覆盖核心服务、AWS 凭证、Bedrock 模型、
S3 技能存储、安全、心跳与可选配置项，每一项均标注默认值与是否必填，便于在生产与开发环境之间快速迁移。
核心服务配置
控制服务运行模式、监听端口、日志级别与 LLM 模拟开关。这些变量在开发与生产环境之间存在差异，
建议通过 .env 文件统一管理。
| 变量 | 说明 | 默认值 | 必填 |
|---|---|---|---|
| MODE | 运行模式：development 或 production | development | 否 |
| WSS_ADDR | WebSocket 监听地址 | :4030 | 否 |
| LOG_LEVEL | 日志级别：DEBUG, INFO, WARN, ERROR, VERBOSE | INFO | 否 |
| LLM_MOCK_MODE | 设为 true 使用模拟 LLM 响应（开发测试用） | false | 否 |
AWS 凭证配置
LingFlow 通过 AWS SDK 访问 Bedrock 与 S3 服务，需配置 IAM 用户凭证与默认区域。
| 变量 | 说明 | 必填 |
|---|---|---|
| AWS_ACCESS_KEY_ID | IAM 用户访问密钥 ID | 是 |
| AWS_SECRET_ACCESS_KEY | IAM 用户秘密访问密钥 | 是 |
| AWS_REGION | 默认 AWS 区域（用于 S3 等服务） | 是 |
AWS Bedrock 配置
Bedrock 是 LingFlow 调用大语言模型的核心通道。区域需与模型可用区域匹配，模型 ID 决定推理能力。
| 变量 | 说明 | 默认值 | 必填 |
|---|---|---|---|
| AWS_BEDROCK_REGION | Bedrock 服务所在区域 | ap-east-1 | 是 |
| AWS_BEDROCK_MODEL_ID | Bedrock 模型标识符 | anthropic.claude-3-5-sonnet-20241022-v2:0 | 是 |
| AWS_BEDROCK_MAX_TOKENS | 响应最大 token 数 | 2048 | 否 |
| AWS_BEDROCK_TEMPERATURE | 采样温度 (0.0-1.0) | 0.7 | 否 |
| AWS_BEDROCK_TOP_P | Top-p 核采样 (0.0-1.0) | 0.9 | 否 |
| AWS_BEDROCK_TIMEOUT | 单次请求超时时长 | 60s | 否 |
常用 Bedrock 模型 ID
不同模型对应的可用区域不同，切换模型时需同步调整 AWS_BEDROCK_REGION。
| 模型名称 | 模型 ID | 可用区域 |
|---|---|---|
| Amazon Nova Lite | amazon.nova-lite-v1:0 | us-east-1 |
| Amazon Nova Pro | amazon.nova-pro-v1:0 | us-east-1 |
| Claude 3.5 Sonnet | anthropic.claude-3-5-sonnet-20241022-v2:0 | us-east-1 |
| Claude 3 Haiku | anthropic.claude-3-haiku-20240307-v1:0 | us-east-1 |
| Llama 3.1 70B | meta.llama3-1-70b-instruct-v1:0 | us-east-1 |
S3 技能存储配置
技能文件以 Markdown 形式存储在 S3 桶中，LingFlow 启动时拉取并周期性校验。
SKILLS_S3_BUCKET 为优先读取项，AWS_SKILLS_S3_BUCKET 为兼容备用项。
| 变量 | 说明 | 默认值 |
|---|---|---|
| SKILLS_S3_BUCKET | 技能文件存储桶名称（优先读取） | — |
| AWS_SKILLS_S3_BUCKET | 技能文件存储桶名称（备用变量，支持 ARN 格式） | — |
| SKILLS_S3_PREFIX | S3 中技能文件的前缀路径 | skills/ |
| S3_REGION | S3 存储桶所在区域（独立于 AWS_REGION） | 继承 AWS_REGION |
arn:aws:s3:::my-bucket），系统会自动提取 bucket 名称。
安全配置
生产环境必须启用 TLS、Token 签名、Origin 白名单与 IP 限流。WSS_ALLOW_ALL_ORIGINS
仅用于本地调试，上线前务必关闭。
| 变量 | 说明 | 默认值 | 生产必填 |
|---|---|---|---|
| WSS_CERT_FILE | TLS 证书文件路径 | — | 是 |
| WSS_KEY_FILE | TLS 私钥文件路径 | — | 是 |
| WSS_AUTH_SECRET | HMAC Token 签名密钥 | — | 是 |
| AUTH_API_KEY | REST 认证接口的 API Key | — | 是 |
| AUTH_TOKEN_TTL | Token 有效期 | 24h | 否 |
| WSS_ALLOWED_ORIGINS | 允许的 Origin 列表（逗号分隔） | — | 是 |
| WSS_MAX_CONNECTIONS_PER_IP | 单 IP 最大连接数 | 10 | 否 |
| WSS_ALLOW_ALL_ORIGINS | 允许所有 Origin（仅调试用） | false | — |
心跳配置
心跳机制用于检测连接活性，超时未活动的连接将被自动断开，避免资源泄漏。
| 变量 | 说明 | 默认值 |
|---|---|---|
| WSS_HEARTBEAT_INTERVAL | 服务端 Ping 发送间隔 | 30s |
| WSS_HEARTBEAT_TIMEOUT | 连接空闲超时（无活动则断开） | 90s |
| WSS_HEARTBEAT_WRITE_TIMEOUT | 写入操作超时 | 10s |
技能创建配置
控制是否允许通过 #create_skill 命令动态生成技能，以及是否启用 Bedrock Guardrail 提示注入防护。
| 变量 | 说明 | 默认值 |
|---|---|---|
| IS_ALLOW_USER_CREATE_SKILL | 是否允许通过 #create_skill 创建技能 | false |
| ENABLE_BEDROCK_GUARDRAIL | 是否启用 Bedrock Guardrail 提示注入防护 | false |
可选配置
支持从 AWS Secrets Manager 拉取密钥，或从 S3 加载 .env 文件，便于在 Serverless 环境中集中管理配置。
| 变量 | 说明 | 默认值 |
|---|---|---|
| SECRET_ARN | AWS Secrets Manager 密钥 ARN | — |
| SECRET_NAME | AWS Secrets Manager 密钥名称 | — |
| S3_ENV_BUCKET | 存储 .env 文件的 S3 桶 | — |
| S3_ENV_KEY | .env 在 S3 中的键名 | .env |
.env 完整示例
以下是一份覆盖核心场景的 .env 模板，复制后按需替换密钥与桶名即可使用。
# 核心配置
MODE=development
WSS_ADDR=:4030
LOG_LEVEL=INFO
LLM_MOCK_MODE=true
# AWS 凭证
AWS_ACCESS_KEY_ID=AKIAxxxxxxxxxxxx
AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxx
AWS_REGION=ap-southeast-5
# S3 技能存储
SKILLS_S3_BUCKET=skill-bucket-bedrock
SKILLS_S3_PREFIX=skills/
S3_REGION=ap-southeast-5
# Bedrock 配置
AWS_BEDROCK_REGION=us-east-1
AWS_BEDROCK_MODEL_ID=amazon.nova-lite-v1:0
AWS_BEDROCK_MAX_TOKENS=2048
AWS_BEDROCK_TEMPERATURE=0.7
AWS_BEDROCK_TOP_P=0.9
AWS_BEDROCK_TIMEOUT=60s
# 技能创建
IS_ALLOW_USER_CREATE_SKILL=true
ENABLE_BEDROCK_GUARDRAIL=false