ccbot资金报表系统配置与运维

ccbot 资金报表系统配置与运维 (v3.2.3 全量架构与加固版)

ccbot 是一个面向多账户财务核算与报表推送的量化辅助系统 (v3.2.3)。它采用前后端分离架构，包括底层的 SQLite 数据归档、FastAPI 只读 API 侧车，以及 Vue 3 + Tailwind 前端看板，统一通过飞书进行日报推送与表单交互。

---

一、 项目目录结构 (Directory Tree)

ccbot/                            # 项目根目录
├── docker-compose.yml            # 容器总编排文件 (串联前后端与网络)
├── .env                          # 全局机密环境变量 (已进行 [REDACTED] 脱敏)
├── data/                         # 挂载卷目录 (用于 SQLite 数据库和日志持久化)
│
├── backend/                      # 后端核心工程 (Python / 飞书机器人内核)
│   ├── Dockerfile.backend        # 后端容器构建脚本
│   ├── requirements.txt          # Python 依赖清单
│   ├── main.py                   # 飞书通信网关与主事件循环 (入口点)
│   ├── api_sidecar.py            # 独立只读 API 网关 (为前端提供数据)
│   ├── handlers.py               # 交互路由、业务逻辑层与卡片生成
│   ├── reporting.py              # 财务核算 (Dietz) 与报表卡片渲染
│   ├── tasks.py                  # 后台调度引擎 (数据自动对账与推送)
│   ├── market_feeds.py           # 外部行情网关 (Tradier、Yahoo 等源的统一出口)
│   ├── database.py               # 异步数据库引擎与 ORM 模型
│   └── config.py                 # 全局配置中心、时间锚点与连接池管理
│
└── frontend/                     # 前端工程 (Vue 3 / Vite / Tailwind UI)
    ├── Dockerfile.frontend       # 前端构建脚本 (Node打包 + Nginx代理)
    ├── nginx.conf                # Nginx 配置 (静态资源托管与 /api 代理转发)
    ├── package.json              # Node.js 项目依赖清单
    ├── vite.config.js            # Vite 构建工具配置
    ├── tailwind.config.js        # Tailwind 样式主题配置
    ├── index.html                # 前端页面物理入口
    └── src/                      # 前端源代码
        ├── main.js               # Vue 实例挂载文件
        ├── App.vue               # 前端看板根组件 (UI 主界面)
        └── index.css             # 全局样式与 Tailwind 核心注入

---

二、 系统配置参数矩阵 (.env 契约)

项目根目录下的 .env 配置文件参数详解：

配置键名	参数类型	默认值 / 推荐值	作用与物理边界
CACHE_TTL_IDLE	浮点数	3600.0	市场闲时（未交易时间）的行情与指标本地缓存生存时间（秒），防限流。
CACHE_TTL_TRADING	浮点数	60.0	市场开盘交易时间段内的缓存生存时间（秒）。
DAILY_REPORT_TIME	时间	06:30	每日触发 Dietz 财务核算并向飞书推送日报的时间（北京时间/CST）。
DB_NAME	路径	data/titan_q_assets.db	核心数据库持久化路径，记录每日账户净值快照（daily_snapshots）。
DIVIDEND_TAX_RATE	比例	0.10	针对账户美股/ETF 分红自动扣除的预扣税率（默认为 10%）。
TRADIER_ACCESS_TOKEN	密钥	[REDACTED]	Tradier API 生产环境访问凭证，必须严格只读授权。
FEISHU_APP_ID	凭证	[REDACTED]	飞书开放平台自建机器人的 App ID。
FEISHU_APP_SECRET	密钥	[REDACTED]	飞书自建机器人的 App Secret，用于生成 tenant_access_token。
FEISHU_REPORT_CHAT_ID	ID	[REDACTED]	接收每日财务核算与估值日报的群组 ID（oc_ 前缀）。

---

二、 部署与运行指令 (Docker Compose)

ccbot 由三个互联的容器构成：写引擎（bot）、读侧车（api）和前端托管（frontend）。

1. 编译并拉起服务 (首次部署/代码更新)

cd /root/HermesAgent/ccbot
 
# 停止旧服务并清理容器
docker compose down
 
# 重新构建镜像并后台拉起
docker compose up -d --build

2. 状态与健康度校验

• 数据库就绪校验：bot 容器自带 Python 脚本健康探测，会核验 daily_snapshots 是否加载完成。
• 查看容器日志：

  # 查看后端机器人日志
  docker logs -f titanq-bot --tail=100
   
  # 查看只读 API 侧车日志
  docker logs -f titanq-api --tail=100

---

三、 日常维护与数据备份

1. 本地数据库安全备份 (SQLite 容灾)

由于数据库在挂载卷中持续处于写状态，严禁直接使用 cp 拷贝，必须执行在线备份（Online Backup）以防止 B-Tree 损坏：

sqlite3 /root/ccbot/data/titan_q_assets.db ".backup '/root/ccbot_backup_$(date +%F).db'"

2. 容器内部测试命令 (手动测试)

在服务启动状态下，可向 bot 容器直接发送指令测试数据核算是否正常：

docker exec -it titanq-bot python test_ccbot.py

相关链接

• clbot对冲策略系统配置与运维 姐妹策略对冲项目运维
• DockerCompose工作流与更新 通用容器平滑更新与空间收回

---

📝 架构迭代与更新日志 (Change Log)

📌 2026-09-19 (v3.2.3 飞书官方 SDK 噪音过滤器与断网自愈控制台静默)

• 【飞书官方 SDK 噪音过滤器 (LarkNoiseFilter)】：在 backend/config.py 与 backend/main.py 引入专属噪音过滤器，精准识别并拦截 lark-oapi 官方 SDK 在公网长连接空闲轮换或心跳断开时误报的 receive message loop exit, err: no close frame received or sent，将其级别重写为 DEBUG，在生产 INFO 模式下完全静默拦截。
• 【第三方 Logger 默认输出清理与双重打印根除】：在 setup_logging 与守护线程初始化阶段，清空 Lark 及第三方 logger 自带的 StreamHandler，挂载全局噪音过滤器并设置 propagate = True，彻底消除第三方库在 stderr 与 root logger 中双重重复打印相同错误日志的现象。
• 【长连接守护重连日志降噪】：将 run_ws_client_with_retry 守护循环中的断线重连与良性网络波动日志降级为 DEBUG，长连接就绪提示仅在服务冷启动时输出一次，保持生产控制台极简高信噪比。

📌 2026-09-07 (v3.2.2 自动派息通知排版细化与告警标签 HTML 裸标签彻底净化)

• 【自动派息通知排版全要素细化】：重构 backend/tasks.py 自动派息汇报卡片，新增底层流水持仓数量（hist_qty 股）、每股派息净额（net_amount）及税前税率说明（如税前 0.15，扣税 10%），计算最终总入账派息现金（cash_amt），信息维度与资金底账完全闭环。
• 【纯文本告警信道 HTML 裸标签净化】：针对飞书 msg_type: text 纯文本告警信道不支持 HTML 解析的问题，全面清除 backend/tasks.py 中的 <code>、</code>、<b>、</b> 标签，统一重构为原生 Markdown / 普通加粗格式（**...**、代码反引号），彻底杜绝手机端飞书裸露 HTML 标签的视觉缺陷。
• 【全系统报告模板与占位符无死角审计】：全面检索排查 ccbot 与 clbot 两个项目的所有报告输出模块（含日报卡片、持仓矩阵、指令帮助、诊断报告），确认无任何悬挂代码、未渲染 HTML 标签或未替换的模板占位符。

📌 2026-09-07 (v3.2.1 全量安全专项加固：API侧车Token准入、NaN数值清洗、群聊会话隔离与HTTPS外联)

本次更新落实了系统安全专项审计整改，强化了数据面校验、网络传输加密与敏感会话隔离：

涉及模块	变更类型	详细修改与底层代码实现
api_sidecar.py	API Sidecar 零信任准入门禁	增加 api_auth_middleware 中间件与 API_SECRET_TOKEN 校验机制，支持 Header (X-TitanQ-Token) 及 Query (?token=) 传递安全令牌；采用 hmac.compare_digest 防时序攻击，未授权请求一律返回 403 阻断，彻底消除未授权脱库隐患。
handlers.py	数值输入强类型清洗与边界	在 cmd_cash、cmd_trade 及 cmd_roll 中全量引入 math.isfinite() 断言，拦截 NaN、Inf 及负数价格注入；标的正则约束为 1 至 32 位长度上限，杜绝超长恶意字符串。
main.py	飞书群聊与私聊密级会话隔离	识别事件消息的 chat_type，当在非私聊（group 群聊）中触发 /pos、/report、/trade 等核心财务指令时，阻断大卡片回帖广播，安全回退为引导用户私聊交互的拦截提示，杜绝财务底牌在群聊中泄露。
market_feeds.py	外汇行情强制 HTTPS 传输	将新浪外汇接口物理链接由 http:// 升级为 https://hq.sinajs.cn/list=fx_susdcny，杜绝中间人劫持与篡改汇率参数。
config.py	Traceback 异常栈递归脱敏	挂载 HardenedMaskingFormatter，重写 formatException 递归过滤 system_audit.log 及标准输出中的 Token、Secret 与账号信息。
test_ccbot_security.py	安全测试套件上线	编写 test_ccbot_security.py 自动化测试，5/5 项安全防御断言 100% 真实通过。

📌 2026-09-10 (v3.2.3 后端全量代码 PEP 8 规范化、Linux LF 换行符统一、注释净化与容器内存硬配额)

涉及模块	变更类型	详细修改与底层代码实现
docker-compose.yml	容器资源内存硬配额 (P0)	显式增加 Deploy Resources 内存上限：titanq-bot (400M)、titanq-api (300M)、titanq-frontend (200M)，彻底杜绝突发流量或扫描穿透打爆宿主机内存造成级联 OOM。
backend/*.py (全量模块)	PEP 8 格式化规范	运用 Ruff 引擎对全部后端 9 个 Python 模块完成 PEP 8 标准排版，统一行宽、缩进与括号对齐，代码洁净度达工业级。
全量源码	换行符统一 (Linux LF)	彻底消除混杂的 Windows \r\n (CRLF) 换行符，全量转换为统一的 \n (LF)，杜绝跨操作系统执行异常。
全量业务注释	注释结构净化	抹除历史版本留存的草稿修复标签（如 # 修复 17...、# 【精确修复】...），重构为语义严密的 # 业务约束: 与 # 核心设计: 规范文档。

📌 2026-09-05 (v3.2.0 代码审查高危缺陷加固：历史回溯对齐、外部现金流分块与未定义变量根除)

涉及模块	变更类型	详细修改与底层代码实现
backend/tasks.py	历史快照回溯取价对齐 (P1)	将历史取价回溯从 range(1, 15) 纠正为 range(0, 15)，优先从当日 (lookback=0) 检索收盘价与汇率，消除历史快照整体系统性错位一天的偏差。
backend/database.py	外部现金流无界 SQL 变量分块防护 (P0)	对 get_external_cash_flows_async 的 batch_ids 实施排他性去重，并引入 chunk_size = 500 的安全分块查询，彻底根治流水累计超过 999 条时 SQLite 触发 too many SQL variables 导致每日日报崩溃的隐患。
backend/tasks.py	未定义变量安全作用域隔离 (P0)	在 job_snapshot_wash 中增加对 alert_logs 的安全作用域判断与防护，杜绝由于外部报价连续断流抛出 NameError 击溃快照洗盘任务。

📌 2026-09-04 (v3.1.0 数据库持久化路径锁定入卷、连接池死锁消除、盘中入金收益纠偏与期权行权前置锁)

本次更新解决了数据库路径易失可能导致数据蒸发、增量洗盘单连接池死锁、盘中入金虚增利润及期权行权交割方向反转等核心架构隐患：

涉及模块	变更类型	详细修改与底层代码实现
config.py / api_sidecar.py	存储路径严格锁定入卷 (P0)	纠正 DB_FILE_PATH 从镜像层 BASE_DIR / DB_NAME 归入 DATA_DIR / DB_NAME（/app/data/titan_q_assets.db），并弹性解析 .env 中带 data/ 前缀及引号的配置，确保主库及 API 只读侧车严格锚定于宿主机 Docker 持久化挂载卷 ./data，根除容器重建数据丢失隐患。
database.py / tasks.py	连接池 Session 复用解除死锁 (P0)	get_max_transaction_id_async 接口扩展为 (session: Optional[AsyncSession] = None)。在 job_snapshot_wash 后台增量洗盘任务中显式透传外层上下文会话，消除在 pool_size=1 约束下同一协程嵌套检出连接引发的连接池耗尽型自死锁（Pool Starvation Deadlock）。
config.py / database.py / tasks.py	异步锁延迟初始化模式 (P0)	将 GlobalResource._get_init_lock()、get_position_write_lock() 及 get_wash_lock() 统一改造为单例工厂方法，杜绝模块顶层直接实例化 asyncio.Lock() 引发的跨事件循环争用与报错。
reporting.py	盘中现金流截断时戳动态对齐 (P1)	改造滚动收益 (Live PnL) 计算：若当前时刻已过 06:00 截断线，现金流过滤窗口从今日早晨 06:00 动态延展至实时的 report_date，彻底消除了盘中充值现金被错误核算为“当日投资收益”的逻辑缺陷。
tasks.py	时区规范化防 8 小时时序倒流 (P1)	历史交易流读取中废弃原 replace(tzinfo=TZ_BJS)，规范采用 ts.replace(tzinfo=timezone.utc).astimezone(TZ_BJS)，保障 SQLite AwareDateTime 存储下的美股盘后交易与跨夜交易时序先后一致。
handlers.py	期权行权前置持仓锁与 Fail-Fast (P1)	在交易流水落盘平仓抹零前，前置核验并锁定 opt_existing_is_long 状态；若账本中未检索到有效期权持仓，坚决触发 Fail-Fast 硬阻断拒绝写入；被指派 Short Call 行权时，底层标的动作严格执行 SELL（卖出股票交付），彻底消除了空头做反敞口翻倍的重大业务风险。
test_ccbot_fixes.py	端到端集成测试套件	新增端到端真实回归测试（涵盖路径锁定、连接池复用、现金流动态截断、Short Call 端到端行权交割与查无持仓 Fail-Fast 阻断，5/5 真实通过）。

📌 2026-08-08 (v2.1.0 飞书 WSS 长连接沙盒隔离与自动重连守护机制)

本次更新彻底消除了 CCBOT 飞书长连接掉线后无法重连的死锁隐患，构建了专属的子线程沙盒生命周期：

• 子线程专属 Event Loop 沙盒 (backend/main.py)：在 run_ws_client_with_retry 内部显式为子线程创建 sub_loop = asyncio.new_event_loop()，并将 event_handler 与 lark.ws.Client 的实例化与启动完全约束在沙盒中，彻底阻断第三方 SDK 尝试绑定主事件循环引发的 This event loop is already running 死锁崩溃。
• 资源显式销毁与防泄漏：在子线程退出时，通过 try...finally 显式执行 sub_loop.shutdown_asyncgens() 与 sub_loop.close()，彻底防止 Socket / Pipe 句柄泄漏引发的 Too many open files 异常。
• 5 秒退避自动重连：当网络波动或服务端每 24 小时强掐时，守护循环捕获异常并在 5 秒后无缝重新发起长连接，保证机器人 7x24 小时在线。