• 后端
• CLI
• MCP 服务
• 即时通讯
• RAG
• 人工智能
• AI 技能

Chatlog Alpha 是一款面向微信 4.x 的本地聊天数据库解密读取与分析工具，提供 TUI 终端界面、Web 控制台、HTTP API 与 MCP 服务，并支持通过 clawbot 接口将全部或指定消息实时推送到 Hermes Weixin / QQ 桥。本文带你快速完成部署，并拆解它如何用 GitHub Actions 一套工作流构建四平台产物、以及围绕密钥做了哪些安全隐私设计。

一、项目定位：解密读取 + 服务化 + 实时推送

在深入部署之前，先了解它的三大能力块，这决定了部署时要关心什么：

完整功能清单与平台兼容性见 README.md。

二、最快部署路径：下载安装包或源码构建

1. 直接下载官方构建产物

项目通过 CI 为macOS 与 Windows 的四种架构组合自动产出压缩包（内含LICENSE和README.md）：

macOS 包还附带start-chatlog.command，双击即可自动定位二进制、恢复执行权限并清理隔离标记，适合不熟悉命令行的用户。

2. 源码构建（5 分钟上手）

git clone https://gitcode.com/gh_mirrors/ch/chatlog_alpha cd chatlog_alpha # 一条命令：清理 + lint + 依赖整理 + 测试 + 构建 make all

Makefile 预置了完整工具链：make lint运行golangci-lint，make test带覆盖率执行go test ./...，make build以CGO_ENABLED=1 go build -trimpath输出当前平台二进制。版本字符串通过git describe自动获取并注入pkg/version.Version，因此发布版--version能准确追溯提交。

💡 环境要求：Go 1.25+、Git、支持 CGO 的 C 编译器；macOS 数据库提钥额外需要 Python 3 与frida-tools。

三、GitHub Actions 构建矩阵拆解：四平台如何一次构建

整个持续集成由单一工作流驱动：.github/workflows/release.yml。它由4 个 job组成，形成"清理 → 双平台构建 → 汇总发布"的流水线。

1. 触发条件与并发控制

on: push: branches: [main] pull_request: branches: [main] workflow_dispatch: concurrency: group: release-${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true

• main分支每次push、每个指向main的 Pull Request 都会触发；也支持手动触发。
• cancel-in-progress: true是关键优化：同一分支的旧任务会被自动取消，避免频繁提交时构建队列堆积浪费 CI 分钟数。

2. 清理旧构建：cleanup-old-builds

发布页采用"滚动更新 latest"策略——旧 Release 先删、新构建再上。该 job 使用ghCLI 完成：

1. 删除旧的latestRelease 及 Git 标签（--cleanup-tag）；
2. 分页遍历并删除旧的release-macos、release-windowsActions Artifacts。

⚠️ 注意：两个步骤都限定github.event_name != 'pull_request' && github.ref == 'refs/heads/main'，即PR 检查时绝不清理，只有主分支真实发布才动生产产物。由于旧 Release 在编译前就被删除，若新构建失败，latest页面会暂时缺失，修复后重新推送即可恢复。

3. macOS 构建：build-macos（amd64 + arm64）

在macos-latest运行器上，一个任务串行构建两个架构：

for arch in amd64 arm64; do CGO_ENABLED=1 GOOS=darwin GOARCH="${arch}" \ go build -trimpath -ldflags "-s -w -X .../version.Version=${GITHUB_REF_NAME}" \ -o "dist/chatlog-darwin-${arch}" . done

构建链包含 5 个质量关卡：

打包前还会用/bin/zsh -n对生成的启动脚本做语法校验，再真实执行一次--help，防止"能编译但脚本坏了"的情况溜进发布页。

4. Windows 构建：build-windows（amd64 + arm64）

Windows 侧的难点是CGO 交叉编译，工作流按架构分两套策略：

# amd64：CGO + MinGW GCC（通过 msys2/setup-msys2 安装 mingw-w64-x86_64-gcc） $env:CC = "gcc"; $env:CGO_ENABLED = "1" go build ... -o "dist/chatlog-windows-amd64.exe" . # arm64：非 CGO 构建，语音转 MP3 等 CGO 能力运行时走提示性兜底 $env:CGO_ENABLED = "0" go build ... -o "dist/chatlog-windows-arm64.exe" .

脚本会先断言gcc已就位（if (-not $gccCmd) { throw ... }），失败时快速报错而不是产出残缺产物。构建前先Remove-Item -Recurse -Force dist, release清工作区，避免上一次残留文件混入压缩包。

5. 汇总发布：publish

publishjob 依赖前两个构建 job 全部成功（needs: [build-macos, build-windows]），在ubuntu-latest上：

1. 用actions/download-artifact拉取release-macos与release-windows两组 Artifacts；
2. find收集所有.zip、.exe与chatlog-darwin-*文件；
3. 通过softprops/action-gh-release创建标签为latest的预发布（prerelease）版本"Latest Build"，make_latest: false保证不抢占用户打过的正式 Release。

这套"先删后建 + prerelease"的组合，让普通用户始终能从latest标签拿到最新一次提交的可运行构建，而开发者可以基于语义化版本打正式发布。

6. 备选的 GoReleaser 方案

仓库还保留了一份 .goreleaser.yaml（v2 配置）：构建前钩子执行go mod tidy，以CGO_ENABLED=1交叉编译 darwin/windows × amd64/arm64，输出 zip 归档与独立二进制两种格式，并生成 SHA256checksums.txt；release.mode: replace与 CI 的滚动策略保持一致。它可作为本地或 tag 触发的补充发布通道。

四、安全与隐私实践：密钥如何被保护

Chatlog Alpha 处理的是个人聊天记录与解密密钥这类高敏感数据，项目在 CI 与运行时两侧都做了防护，值得同类工具借鉴。

1. 密钥文件最小权限

数据库密钥映射all_keys.json在 macOS（internal/wechat/key/darwin/frida.go 中经writeFileAtomic原子写入）和 Windows（internal/wechat/key/windows/data_key_windows.go）两侧均以0600权限落盘——仅属主可读写，其他用户连读都不行。README 也明确告诫：不要把密钥、解密数据库或聊天内容提交进 Git 仓库。

2. 状态接口默认脱敏

action status这类机器可读的状态接口从不回传密钥原文。internal/chatlog/action.go 中的实现只暴露布尔位与占位符：

DataKeyPresent: dataKey != "", DataKey: redactActionSecret(dataKey), // 非空时固定返回 "******"

自动化脚本能判断"密钥是否就绪"，却永远拿不到密钥本身——即使日志被意外打印，泄密的也只是星号。

3. 高危操作仅限本机回环

发信调试（Frida Hook 发送消息）是能力最强的接口，也是最危险的：一旦可被远程调用，等于把"代你发消息"的能力交给了局域网。项目在 internal/chatlog/http/send_debug.go 中加了硬门禁：

func requireLocalDebugRequest(c *gin.Context) bool { if isLoopbackRemote(c.Request.RemoteAddr) { return true } c.JSON(403, gin.H{"error": "Frida 发信调试仅允许从本机 Web 控制台调用"}) c.Abort() return false }

即使 HTTP 服务监听在0.0.0.0:5030对整个局域网可见，来自非回环地址的请求也会被 403 拒绝。

4. CORS 与 Host 边界检查

internal/chatlog/http/middleware.go 实现了细粒度的跨域策略：

• 服务绑定回环地址时，仅放行来自回环地址的请求（requestHostAllowed）；
• 通配符绑定（0.0.0.0）时，Origin主机必须属于私网/链路本地地址才放行；
• 不匹配的跨站请求直接403，防止浏览器端脚本被第三方页面借机调用。

配套测试 internal/chatlog/http/middleware_test.go 覆盖了"跨站 origin 拒绝"等用例。MCP 内部转发同样通过 internal/chatlog/http/mcp.go 的loopbackCompatAddress把0.0.0.0、::等通配符归一化为127.0.0.1，保证内部调用永不指向外部地址。

5. 依赖漏洞扫描进 CI

macOS 构建任务在编译前固定执行：

go run golang.org/x/vuln/cmd/govulncheck@v1.6.0 ./...

govulncheck不是简单比对版本号，而是基于调用图分析判断有漏洞的函数是否真的被本项目调用，能显著减少"依赖链里带毒但实际不可达"的误报。这意味着每次发布构建都自带一轮安全体检，且社区通过 Dependabot 持续跟进x/crypto、x/net等基础库的安全修复（见 README.md 贡献记录）。

6. 本地优先的模型数据边界

语义检索等 AI 能力默认指向本地 Ollama（http://127.0.0.1:11434，见 internal/chatlog/conf/semantic.go）。README 明确告知用户：使用 GLM、DeepSeek 等远程模型时，选中的检索文本会发送到所配置的模型服务；改用 Ollama 或本地 llama.cpp 服务则可让模型处理完全留在本机。把数据去向讲清楚，是隐私实践里容易被忽略却最重要的一环。

五、关键文件速查

小结

Chatlog Alpha 的 CI 设计有几个值得借鉴的要点：单工作流 + 双平台 job覆盖四平台矩阵；concurrency取消旧任务节省 CI 资源；PR 检查与主分支发布严格隔离；测试、漏洞扫描、冒烟测试三级质量门禁前置到发布之前。而安全侧则以"密钥最小权限落盘 + 接口脱敏 + 高危操作仅限回环 + CORS 边界检查"四道防线，配合"本地优先"的模型数据策略，把一个直接接触聊天记录的工具守在了用户自己的机器里。对于同样需要处理敏感本地数据的 Go 项目，这套 CI 模板与安全细节几乎可以直接复用。

• 后端
• CLI
• MCP 服务
• 即时通讯
• RAG
• 人工智能
• AI 技能