Bitcart 0.10.3.0 配置参数详解

目标：讲清 Bitcart 0.10.3.0 的配置读取机制（API 与 daemon 双体系、优先级规则、生效方式），按分类给出全部核心参数的环境变量名、默认值与说明，关键参数均附真实服务器实测验证回显，并提供生产配置模板。

一、配置体系总览

Bitcart 的配置分为两个独立体系，都从 Bitcart 仓库根目录下的 conf/.env 文件读取：

优先级规则（从高到低，已实测验证，见 2.3 节）：

进程环境变量（systemd Environment= / export）  >  conf/.env  >  代码内默认值

生效方式：conf/.env 是进程启动时一次性读取的静态文件，修改后必须重启对应服务（systemctl restart <服务名>）才会生效。

二、查看与修改配置（实测）

2.1 查看当前配置

cat /opt/bitcart/bitcart/conf/.env

实测输出（最小安装配置）：

DB_PASSWORD=q1w2e3r4
BITCART_CRYPTOS=btc

查看 systemd 层注入的环境变量（优先级高于 conf/.env）：

systemctl show bitcart-api --property=Environment

实测输出：

Environment=BITCART_API_WORKERS=2

2.2 修改配置的标准步骤

1. 编辑 conf/.env（每行一个 KEY=VALUE）；
2. 重启消费该参数的服务：API/worker 参数重启 bitcart-api、bitcart-worker；daemon 参数重启对应的 bitcart-<coin>-daemon；
3. 用可观测端点验证（如 /cryptos、daemon getinfo）。

2.3 优先级实测：环境变量 > conf/.env

在 conf/.env 中追加 BITCART_API_WORKERS=3（单元文件中已通过 Environment=BITCART_API_WORKERS=2 设为 2），重启 API 后统计 gunicorn 实际拉起的 worker 数：

printf "BITCART_API_WORKERS=3\n" >> /opt/bitcart/bitcart/conf/.env
systemctl restart bitcart-api
journalctl -u bitcart-api --since "-2 min" --no-pager | grep -cE "Booting worker with pid"

实测输出：

2

worker 数为 2（单元文件的值）而非 3（conf/.env 的值），证实进程环境变量优先。测试完成后应从 conf/.env 移除该行，避免误导后续维护。

该机制的反向用法：需要在 systemd 层固定某个参数时，写入单元文件的 Environment= 并 systemctl daemon-reload；只在 conf/.env 修改时，务必确认没有同名环境变量遮蔽。

三、API / worker 参数详解

以下参数均来自 0.10.3.0 源码 api/settings.py，默认值为代码缺省值。「环境变量名」即写入 conf/.env 或单元文件时使用的名字。

3.1 环境与调试

3.2 数据库（PostgreSQL）

3.3 Redis

Redis 是 API 的硬依赖（缓存与进程间通信），连接失败会导致 API 全部路由返回 500（实测排障见安装指南 6.5 节）。

3.4 币种与汇率

3.5 网络与域名

3.6 日志体系与 LOG_FILE 的生效范围（重要实测发现）

API 的日志架构在源码手动部署（gunicorn 托管）下与直觉不同，以下均为实测结论：

1. 应用日志不走 stdout。gunicorn 模式下 API 应用日志通过 msgpack socket 发送给 logserver 进程（默认 localhost 的日志端口；Docker 部署中为 worker 容器），journalctl -u bitcart-api 只能看到 gunicorn/uvicorn 的生命周期日志（启动、worker 拉起、未处理异常堆栈）：

Oct 22 17:57:38 bitcart-native gunicorn[10676]: [2026-10-22 17:57:38 +0000] [10676] [INFO] Booting worker with pid: 10676
Oct 22 17:57:39 bitcart-native gunicorn[10676]: 2026-10-22 17:57:39.912219 UTC [info] Application startup complete.  [uvicorn.error]

2. LOG_FILE 仅在 logserver 模式生效。实测在 conf/.env 配置 LOG_FILE=bitcart.log 后重启 API，仓库 data/logs/ 目录并未生成（文件日志处理器只在 logserver 运行模式中挂载）。因此不要依赖 LOG_FILE 做手动部署的日志收集。
3. 手动部署下排查 API 行为的可用途径：journalctl -u bitcart-api（生命周期与异常堆栈）、/cryptos 等端点验证、以及 BITCART_OTEL_ENABLED=true 接入 OpenTelemetry 收集器（需安装 otel 依赖组并自备 collector）。

3.7 目录与数据

实测确认 data/ 下会自动创建 files/、images/、admin_plugins/、store_plugins/、docker_plugins/、backups/ 等子目录。

3.8 API 元数据与服务参数

3.9 许可、更新与监控

四、daemon 参数详解（币种前缀体系）

daemon 体系从 conf/ 目录读取参数，每个币种同构，环境变量名为 {币种大写代号}_{参数名}。同时 daemon 支持一组无前缀的通用变量（在 daemon 进程层面读取）。

4.1 通用参数

4.2 各币种默认端口

daemon RPC 默认端口（0.10.3.0 源码 daemons/ 目录定义，API 依赖该端口表连接各 daemon）：

4.3 BTC_NETWORK 实测：切换 testnet

在 conf/.env 加入 BTC_NETWORK=testnet 并重启 daemon：

printf "DB_PASSWORD=q1w2e3r4\nBITCART_CRYPTOS=btc\nBTC_NETWORK=testnet\n" > /opt/bitcart/bitcart/conf/.env
systemctl restart bitcart-btc-daemon
sleep 8
curl -s -X POST http://127.0.0.1:5000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(printf "electrum:electrumz" | base64)" \
  -d '{"jsonrpc":"2.0","id":0,"method":"getinfo","params":[]}'

实测输出：

{"jsonrpc": "2.0", "result": {"network": "testnet", "path": "/home/bitcart/.electrum/testnet", "server": "blackie.c3-soft.com", "blockchain_height": 4431167, "server_height": 5196093, "spv_nodes": 3, "connected": true, "auto_connect": true, "version": "4.6.0b1", "fee_estimates": {"1008": 1002, "144": 1002, "25": 1002, "10": 1002, "5": 1002, "2": 1002}, "synchronized": true, "total_wallets": 0}, "id": 0}

三个关键变化：network 变为 testnet；数据目录自动隔离为 /home/bitcart/.electrum/testnet（与 mainnet 数据互不影响）；连接的服务器切换为 testnet Electrum 服务器池（spv_nodes: 3）。

移除 BTC_NETWORK 恢复 mainnet 后实测：

{"jsonrpc": "2.0", "result": {"network": "mainnet", "path": "/home/bitcart/.electrum", "server": "bitcoin.lu.ke", "blockchain_height": 972640, "server_height": 972640, "spv_nodes": 6, "connected": true, ...}}

4.4 BTC_DEBUG 实测：daemon 调试日志

在 conf/.env 加入 BTC_DEBUG=true 并重启 daemon 后，journalctl 中出现 Electrum 内核的详细日志（正常模式下仅启动/错误行）：

2026-10-22 17:58:18.091187 UTC [info] fee_estimates {1008: 100, 144: 136, 25: 143, 10: 983, 5: 1812, 2: 2231} [electrum.network.Network]
2026-10-22 17:58:18.420459 UTC [info] set blockchain with height 972640 [electrum.interface.Interface.[ecdsa.net:110]]
2026-10-22 17:58:19.837222 UTC [info] fee_histogram 14 [electrum.network.Network]

排查 daemon 连接问题时开启，平时保持关闭以减少日志量。

4.5 daemon RPC 认证

daemon 的 JSON-RPC 端口受 Basic 认证保护，默认凭据 electrum:electrumz。生产环境应通过 {COIN}_LOGIN / {COIN}_PASSWORD 覆盖，并在 API 侧（conf/.env 对应币种凭据）同步修改。本地验证示例：

curl -s -X POST http://127.0.0.1:5000 \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(printf "electrum:electrumz" | base64)" \
  -d '{"jsonrpc":"2.0","id":0,"method":"getinfo","params":[]}'

凭据错误时 daemon 返回 Unauthorized。

五、生产配置模板

以下为手动部署（Ubuntu 22.04，路线见安装指南）的生产配置模板，写入 /opt/bitcart/bitcart/conf/.env：

# ===== 必配 =====
DB_PASSWORD=<强密码>
BITCART_CRYPTOS=btc

# ===== 环境与日志 =====
BITCART_ENV=production
LOG_LEVEL=INFO

# ===== 数据库 / Redis（默认本机时可省略，集中部署时必须显式） =====
# DB_HOST=127.0.0.1
# DB_PORT=5432
# DB_USER=postgres
# DB_DATABASE=bitcart
# DB_POOL_SIZE=5
# REDIS_HOST=127.0.0.1
# REDIS_PORT=6379

# ===== 对外域名（与反代配置一致） =====
BITCART_HOST=bitcart.example.com
BITCART_HTTPS_ENABLED=true
BITCART_REVERSEPROXY=nginx-https

# ===== daemon 侧（每币种同构，按需启用） =====
BTC_LOGIN=<自定义RPC用户>
BTC_PASSWORD=<自定义RPC密码>
# BTC_NETWORK=mainnet
# BTC_DEBUG=false

配套建议：

• BITCART_API_WORKERS 通过 systemd 单元 Environment= 设置（优先级最高），小内存服务器设 2；
• daemon RPC 监听 127.0.0.1，不要对公网放行 5000-5011 端口；
• 修改任一参数后重启对应服务：systemctl restart bitcart-btc-daemon bitcart-api bitcart-worker；
• Docker Compose 部署的配置走 bitcart-docker 环境变量机制（生成 compose/generated.yml），不要直接改生成文件，详见《Bitcart 0.10.3.0 Docker Compose 部署指南》（/post/9QtDWOa9H4Gc）。

六、常见问题

6.1 修改配置后不生效

排查顺序：确认改对了文件（conf/.env，路径在 bitcart 仓库根目录）→ 确认重启了消费该参数的服务 → 确认没有更高优先级的同名环境变量（systemctl show <服务> --property=Environment）→ Docker 部署确认重新执行了 ./setup.sh。

6.2 journalctl 里看不到 API 应用日志

属正常现象：gunicorn 模式下应用日志走 logserver msgpack 通道（见 3.6 节），journalctl 只有生命周期日志。排查功能问题优先使用 API 端点验证与异常堆栈，需要全量日志时接入 OpenTelemetry。

6.3 testnet 数据会污染 mainnet 吗

不会。daemon 数据目录按网络自动隔离（实测：mainnet 为 /home/bitcart/.electrum，testnet 为 /home/bitcart/.electrum/testnet），切换网络不影响另一网络的钱包数据。

七、下一步

• 安装过程回顾：《Bitcart 0.10.3.0 Ubuntu 22.04 安装指南》（/post/9HkLvzFW4ZKO）
• 容器化部署配置机制：《Bitcart 0.10.3.0 Docker Compose 部署指南》（/post/9QtDWOa9H4Gc）
• 命令行工具与日常运维：《Bitcart 0.10.3.0 常用 CLI 命令与工具详解》（/post/rJ9RlrUrPXxU）
• 组件定位与选型：《Bitcart 0.10.3.0 介绍与选型指南》（/post/yKeVQmbN4Q6d）