Docker 部署指南

部署准备

由于 Docker 容器运行环境与宿主机隔离，无法直接获取微信进程密钥，因此需要预先在宿主机上获取密钥信息。

获取微信密钥

在宿主机上运行 chatlog 获取密钥信息：

# 下载并运行 chatlog
$ chatlog key

# 输出示例
Data Key: [c0163e***ac3dc6]
Image Key: [38636***653361]

💡 提示:

macOS 用户需要临时关闭 SIP 才能获取密钥，详见 macOS 版本说明

定位微信数据目录

根据不同操作系统，微信数据目录位置如下：

Windows 系统:

# 微信 3.x 版本
C:\Users\{用户名}\Documents\WeChat Files\{微信ID}

# 微信 4.x 版本
C:\Users\{用户名}\Documents\xwechat_files\{微信ID}

macOS 系统:

# 微信 3.x 版本
/Users/{用户名}/Library/Containers/com.tencent.xinWeChat/Data/Library/Application Support/com.tencent.xinWeChat/{版本号}/{微信ID}

# 微信 4.x 版本
/Users/{用户名}/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/{微信ID}

Docker 镜像获取

chatlog 提供了两个镜像源：

Docker Hub:

docker pull sjzar/chatlog:latest

GitHub Container Registry (ghcr):

docker pull ghcr.io/sjzar/chatlog:latest

💡 镜像地址:

Docker Hub: https://hub.docker.com/r/sjzar/chatlog

GitHub Container Registry: https://ghcr.io/sjzar/chatlog

部署方式

Docker Run 方式

基础部署:

docker run -d \
  --name chatlog \
  -p 5030:5030 \
  -v /path/to/your/wechat/data:/app/data \
  sjzar/chatlog:latest

这种部署方式依赖于数据目录下的 chatlog.json 文件作为配置，通过 chatlog 获取密钥时将自动更新 chatlog.json 文件

完整配置示例:

docker run -d \
  --name chatlog \
  -p 5030:5030 \
  -e TZ=Asia/Shanghai \
  -e CHATLOG_PLATFORM=darwin \
  -e CHATLOG_VERSION=4 \
  -e CHATLOG_DATA_KEY="your-data-key" \
  -e CHATLOG_IMG_KEY="your-img-key" \
  -e CHATLOG_AUTO_DECRYPT=true \
  -e CHATLOG_HTTP_ADDR=0.0.0.0:5030 \
  -e CHATLOG_DATA_DIR=/app/data \
  -e CHATLOG_WORK_DIR=/app/work \
  -v /path/to/your/wechat/data:/app/data \
  -v /path/to/work:/app/work \
  --restart unless-stopped \
  sjzar/chatlog:latest

Docker Compose 方式

1. 创建 docker-compose.yml 文件

version: '3.8'

services:
  chatlog:
    image: sjzar/chatlog:latest
    restart: unless-stopped
    ports:
      - "5030:5030"  # 可修改主机端口，如 "8080:5030"
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      # 微信平台类型，可选：windows, darwin
      - CHATLOG_PLATFORM=darwin
      # 微信版本，可选：3, 4
      - CHATLOG_VERSION=4
      # 微信数据密钥
      - CHATLOG_DATA_KEY=your-data-key
      # 微信图片密钥
      - CHATLOG_IMG_KEY=your-img-key
      # 是否自动解密
      - CHATLOG_AUTO_DECRYPT=true
      # 服务地址
      - CHATLOG_HTTP_ADDR=0.0.0.0:5030
      # 数据目录
      - CHATLOG_DATA_DIR=/app/data
      # 工作目录
      - CHATLOG_WORK_DIR=/app/work
    volumes:
      # 微信数据目录挂载
      - "/path/to/your/wechat/data:/app/data"
      # 工作目录挂载
      - "work-dir:/app/work"

volumes:
  work-dir:
    driver: local

2. 启动服务

# 启动服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看服务日志
docker-compose logs chatlog

# 停止服务
docker-compose down

环境变量配置

变量名	说明	默认值	示例
`PUID`	用户 ID	`1000`	`1000`
`PGID`	用户组 ID	`1000`	`1000`
`TZ`	时区设置	`UTC`	`Asia/Shanghai`
`CHATLOG_PLATFORM`	微信平台类型	必填	`windows`, `darwin`
`CHATLOG_VERSION`	微信版本	必填	`3`, `4`
`CHATLOG_DATA_KEY`	微信数据密钥	必填	`c0163e***ac3dc6`
`CHATLOG_IMG_KEY`	微信图片密钥	可选	`38636***653361`
`CHATLOG_HTTP_ADDR`	HTTP 服务监听地址	`0.0.0.0:5030`	`0.0.0.0:8080`
`CHATLOG_AUTO_DECRYPT`	是否自动解密	`false`	`true`, `false`
`CHATLOG_DATA_DIR`	数据目录路径	`/app/data`	`/app/data`
`CHATLOG_WORK_DIR`	工作目录路径	`/app/work`	`/app/work`

数据目录挂载

微信数据目录

Windows 示例:

# 微信 4.x 版本
-v "/c/Users/username/Documents/xwechat_files/wxid_xxx:/app/data"

# 微信 3.x 版本
-v "/c/Users/username/Documents/WeChat\ Files/wxid_xxx:/app/data"

macOS 示例:

# 微信 4.x 版本
-v "/Users/username/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_xxx:/app/data"

# 微信 3.x 版本
-v "/Users/username/Library/Containers/com.tencent.xinWeChat/Data/Library/Application\ Support/com.tencent.xinWeChat/2.0b4.0.9:/app/data"

工作目录

工作目录用于存放解密后的数据库文件，可以使用以下两种方式：

本地路径方式:

-v "/path/to/local/work:/app/work"

命名卷方式:

-v "chatlog-work:/app/work"

远程同步部署

对于需要将 chatlog 服务与微信客户端分离部署的场景，可以通过文件同步工具将微信数据同步到远程服务器，然后在远程服务器上运行 chatlog 服务。这种方式具有以下优势：

解耦部署：微信客户端和 chatlog 服务可以运行在不同的设备上
灵活性：可以在 NAS、VPS 等服务器上统一管理聊天数据
安全性：避免在个人电脑上长期运行服务

文件同步工具这里不做过多推荐，个人使用 Syncthing，其他选择有 Resilio Sync、rsync + inotify 等，可以按需选择。

配置指南

本地配置: 同步数据目录(Data Dir)，可设置为仅发送；在首次完整同步文件后，建议将 "rescanIntervalS" 设置为 0，全局扫描较为耗时，且扫描过程中会暂停同步
远程服务器配置: 设置为仅接收，同样建议将 "rescanIntervalS" 设置为 0
使用 Docker / Docker Compose 启动 chatlog，将数据目录映射到容器的 /app/data 目录
按需配置 /app/work 映射目录，可配置到远程服务器本地路径或命名卷
启动容器后，等待首次解密完成后，即可正常请求 API 或接入 MCP 服务

部署注意事项

千万注意数据安全！chatlog 本身未提供授权机制，一定要确保服务处于安全网络环境中。

通过远程同步部署，您可以在保持微信客户端正常使用的同时，将 chatlog 服务部署到更适合的环境中，实现数据处理与日常使用的分离。

部署验证

部署完成后，通过以下方式验证服务是否正常运行：

1. 检查容器状态

docker ps | grep chatlog

2. 查看服务日志

docker logs chatlog

3. 访问 HTTP API

# 检查服务健康状态
curl http://localhost:5030/api/v1/session

# 查看联系人列表
curl http://localhost:5030/api/v1/contact

4. 访问 MCP 服务

http://localhost:5030/mcp

5. 访问 Web 界面

在浏览器中打开：http://localhost:5030

常见问题

1. 容器启动失败

问题: 容器启动后立即退出

解决方案:

检查密钥是否正确：docker logs chatlog
确认数据目录挂载路径是否正确
检查环境变量配置是否完整

2. 无法访问 HTTP 服务

问题: 浏览器无法访问 http://localhost:5030

解决方案:

检查端口映射是否正确：docker port chatlog
确认防火墙是否允许 5030 端口访问
检查容器内服务是否正常启动

3. 数据目录权限问题

问题: 日志显示权限不足或文件无法访问

解决方案:

# Linux/macOS 系统
chmod -R 755 /path/to/your/wechat/data

# 或者使用 Docker 用户权限
docker run --user $(id -u):$(id -g) ...

4. 密钥格式错误

问题: 显示密钥格式不正确

解决方案:

确保密钥为十六进制格式，不包含方括号
正确格式：CHATLOG_DATA_KEY=c0163eac3dc6
错误格式：CHATLOG_DATA_KEY=[c0163e***ac3dc6]

5. 微信版本检测失败

问题: 无法自动检测微信版本

解决方案:

手动设置微信平台：CHATLOG_PLATFORM=darwin 或 CHATLOG_PLATFORM=windows
手动设置微信版本：CHATLOG_VERSION=4 或 CHATLOG_VERSION=3

6. 端口冲突

问题: 5030 端口已被占用

解决方案:

# 使用其他端口，如 8080
docker run -p 8080:5030 ...

# 或在 docker-compose.yml 中修改
ports:
  - "8080:5030"

💡 获取更多帮助: 如遇到其他问题，请查看项目的 Issues 页面或提交新的问题反馈。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docker 部署指南

目录

部署准备

获取微信密钥

定位微信数据目录

Docker 镜像获取

部署方式

Docker Run 方式

Docker Compose 方式

环境变量配置

数据目录挂载

微信数据目录

工作目录

远程同步部署

配置指南

部署注意事项

部署验证

常见问题

1. 容器启动失败

2. 无法访问 HTTP 服务

3. 数据目录权限问题

4. 密钥格式错误

5. 微信版本检测失败

6. 端口冲突

FilesExpand file tree

docker.md

Latest commit

History

docker.md

File metadata and controls

Docker 部署指南

目录

部署准备

获取微信密钥

定位微信数据目录

Docker 镜像获取

部署方式

Docker Run 方式

Docker Compose 方式

环境变量配置

数据目录挂载

微信数据目录

工作目录

远程同步部署

配置指南

部署注意事项

部署验证

常见问题

1. 容器启动失败

2. 无法访问 HTTP 服务

3. 数据目录权限问题

4. 密钥格式错误

5. 微信版本检测失败

6. 端口冲突