env.example

# 复制为 .env 并填写实际值。地图底图单独选择，地点与路线服务按区域自动选择。
# 修改服务端变量后重启/重新部署；NEXT_PUBLIC_* 变量需在构建前设置。

# ── 地图渲染 ─────────────────────────────────────────────
# osm：MapLibre + OpenStreetMap（默认）
# amap：按现有 isInChina 判断地图中心，境内高德 JS API 2.0，境外 Google Maps JS；移动结束后自动切换
MAP_RENDERER=osm

# 仅 MAP_RENDERER=amap 时必填：高德控制台申请「Web端(JS API)」Key。
# 安全密钥与这个 JS Key 配套，不是下面的 Web 服务 Key。
# 在高德控制台配置自己的部署域名白名单。
# 当前实现将 JS Key 和安全密钥下发浏览器，用于 _AMapSecurityConfig。
AMAP_JS_KEY=
AMAP_JS_SECURITY_CODE=

# MAP_RENDERER=amap 时，境外底图需要 Google Maps JavaScript API 和计费。
# 可选专用浏览器 Key，配置网站域名限制；留空复用 GOOGLE_API_KEY。
# 浏览器地图 Key 会下发前端，不能对它设置仅允许服务端 IP 的限制。
GOOGLE_JS_KEY=

# 仅 osm 使用：true（默认）走同源 /osm-tiles/{z}/{x}/{y}.png，
# 需 nginx/CDN 配置代理 https://tile.openstreetmap.org/。
# false：浏览器直接访问 OSM 官方瓦片，无需反代；本地无代理时使用此值。
# 构建时生效。当前 Docker 未透传此构建参数，Compose 部署默认需配置瓦片反代。
NEXT_PUBLIC_OSM_TILE_PROXY=true

# ── 地点服务（与地图渲染引擎独立）─────────────────────────
# 自动按现有 isInChina 函数选取：境内高德优先，失败或无有效结果时回退 Google；境外 Google。
# 搜索以范围中心判断；无范围时 country=CN（默认）使用高德，否则 Google。
# 多目的地旅行搜索分别查询各中心附近；目的地省市查询复用两组 Key（高德地理编码、Google Geocoding），无需新增变量。
# 跨境路线不请求寻路，显示两点距离与虚线。后端服务与前端按中心切换底图独立。
# 旧 MAP_SEARCH_PROVIDER / MAP_DETAILS_PROVIDER / MAP_DIRECTIONS_PROVIDER 不再参与默认选择。

# 海外服务与境内回退需要 Google API Key。
# 当前调用旧版接口：启用 Places API（Legacy）、Geocoding API、Directions API（Legacy）。
# Places API (New) / Routes API 不能代替；新项目需先确认 Google 是否允许开通旧版 API。
# 服务端 Key 建议限制出口 IP；网页使用独立 GOOGLE_JS_KEY，iOS 原生使用独立 Maps SDK for iOS Key。
# BASE_URL 可改为你的 Google API 反向代理地址；通常保留默认值。
GOOGLE_API_KEY=
GOOGLE_API_BASE_URL=https://maps.googleapis.com

# 境内服务需要高德控制台申请的「Web服务」Key。
# 需具备 POI 搜索（关键字/多边形/详情）、地理编码/逆地理编码、步行/驾车/骑行/公交路径规划权限与配额。
# 不要填 AMAP_JS_KEY：JS 地图和后端 Web 服务使用两种不同类型的 Key。
# iOS 原生底图另申请 iOS 平台 Key，放 iOS 构建配置，不放本站 .env。
AMAP_API_KEY=
AMAP_API_BASE_URL=https://restapi.amap.com

# ── 数据存储与访问认证 ───────────────────────────────────
# SQLite 默认 ./data/mapannai.db；Compose 将 /app/data 持久化到命名卷。
# 自定义路径需位于持久化挂载目录内，数据库同时保存地点、旅行与路线缓存。
# SQLITE_PATH=/data/mapannai.db

# 留空不启用 API 认证；配置后前端弹窗输入同一个 token。
# MCP 使用 Authorization: Bearer <token>，或 x-api-token: <token>。
API_TOKEN=

# ── 网页 AI 对话（可选）───────────────────────────────────
# API 地址、Key、模型在网页“AI 规划”中配置，聊天记录保存在用户浏览器。
# 服务端默认仅允许公共 HTTPS AI API，阻止私有地址并且不跟随重定向。
# 自托管模型需要私有网络或 HTTP 时由部署者显式启用；地址需从服务端可达。
# Docker 中 localhost 指容器自身。开启后建议配置上面的 API_TOKEN 限制访问。
AI_ALLOW_PRIVATE_ENDPOINTS=false

# ── AI 联网（可选，官方 MCP 转发）────────────────────────
# 单容器 Node 22 内通过 stdio 调用固定版本的官方 MCP，无额外端口/URL。
# Key 仅在服务器 .env 中填写；未配置对应 Key 时不注册工具。
BRAVE_API_KEY=
FIRECRAWL_API_KEY=
# 搜索/页面内容经第三方服务处理，可能产生费用；不要查询私人信息。

# ── 腾讯云 COS（可选，用于图片上传）───────────────────────
TENCENT_COS_SECRET_ID=
TENCENT_COS_SECRET_KEY=
TENCENT_COS_REGION=ap-chongqing
TENCENT_COS_BUCKET=
# 构建时设置，多个图片域名用英文逗号分隔，仅填域名不含协议。
# NEXT_PUBLIC_IMAGE_DOMAINS=your-bucket.cos.ap-chongqing.myqcloud.com
# 地址后台补全无需额外变量：Node 启动即扫描，完成后每小时再次扫描。
# 复用 AMAP_API_KEY / GOOGLE_API_KEY；国内高德优先并回退 Google，境外 Google。
# 仅补全空地址，可能产生地图 API 费用，需要持续运行 Node 服务。

# ── AI Agent（同一容器内独立进程） ─────────────────────────────────────
# Web 仍提供原 /api/ai/chat，内部通过 WebSocket 调用 Agent；浏览器无需改地址。
# Docker 默认同一容器内通过回环通信，不公开 Agent 端口；所有配置集中在本目录 .env。
AGENT_URL=http://127.0.0.1:3100
AGENT_MCP_URL=http://127.0.0.1:3000/api/mcp
AGENT_HOST=127.0.0.1
AGENT_PORT=3100
# Web 与 Agent 共享的可选内部凭据，不是模型 Key；非回环监听必须设置。
# 可用 openssl rand -hex 32 生成；不要提交或发送到浏览器。
AGENT_TOKEN=

# Agent 独立执行日志（不与地图 DB 共用）；仅支持单个 Agent 进程持有。
# 保存最终消息与工具结果，不保存模型 Key。请持久化并按私有会话数据管理。
AGENT_SQLITE_PATH=./data/agent.db

# 诊断 transcript 开关：记录请求消息、模型调用、节点、工具结果与错误栈。
# 写入同一 AGENT_SQLITE_PATH 数据库 trace_records 表，不新增容器或日志目录。
# 未设置时开发默认开启、生产默认关闭；true/false 显式覆盖。
# 开启后包含私人对话/工具资料，凭据尽力脱敏，禁止公开数据库。
# 保留7天（启动及写入时清理），每次执行最多2000万字符，超出不再记录。
# AGENT_TRACE_ENABLED=false

# ── 预构建镜像（可选，docker-compose.ghcr.yml 使用）─────────
# 默认拉取正式版 latest；手动默认分支构建使用 edge，或固定实际已发布的版本标签。
# MAPANNAI_IMAGE=ghcr.io/ricterz/mapannai-plus:latest
# NEXT_PUBLIC_IMAGE_DOMAINS 不能通过容器运行参数修改；自建镜像时设置同名 Actions 仓库变量。

# 火车关联线使用内置中国/日本 OSM 铁路及独立日本地铁快照，本地绘图无需联网或额外 Key；无离线路径时按原规则回退高德/Google（使用已有的服务Key）。