358 lines
9.9 KiB
Markdown
358 lines
9.9 KiB
Markdown
# Docker 部署指南
|
|
|
|
## 目录
|
|
- [Docker 部署指南](#docker-部署指南)
|
|
- [目录](#目录)
|
|
- [部署准备](#部署准备)
|
|
- [获取微信密钥](#获取微信密钥)
|
|
- [定位微信数据目录](#定位微信数据目录)
|
|
- [Docker 镜像获取](#docker-镜像获取)
|
|
- [部署方式](#部署方式)
|
|
- [Docker Run 方式](#docker-run-方式)
|
|
- [Docker Compose 方式](#docker-compose-方式)
|
|
- [环境变量配置](#环境变量配置)
|
|
- [数据目录挂载](#数据目录挂载)
|
|
- [微信数据目录](#微信数据目录)
|
|
- [工作目录](#工作目录)
|
|
- [远程同步部署](#远程同步部署)
|
|
- [配置指南](#配置指南)
|
|
- [部署注意事项](#部署注意事项)
|
|
- [部署验证](#部署验证)
|
|
- [常见问题](#常见问题)
|
|
- [1. 容器启动失败](#1-容器启动失败)
|
|
- [2. 无法访问 HTTP 服务](#2-无法访问-http-服务)
|
|
- [3. 数据目录权限问题](#3-数据目录权限问题)
|
|
- [4. 密钥格式错误](#4-密钥格式错误)
|
|
- [5. 微信版本检测失败](#5-微信版本检测失败)
|
|
- [6. 端口冲突](#6-端口冲突)
|
|
|
|
## 部署准备
|
|
|
|
由于 Docker 容器运行环境与宿主机隔离，无法直接获取微信进程密钥，因此需要预先在宿主机上获取密钥信息。
|
|
|
|
### 获取微信密钥
|
|
|
|
在宿主机上运行 chatlog 获取密钥信息：
|
|
|
|
```shell
|
|
# 下载并运行 chatlog
|
|
$ chatlog key
|
|
|
|
# 输出示例
|
|
Data Key: [c0163e***ac3dc6]
|
|
Image Key: [38636***653361]
|
|
```
|
|
|
|
> 💡 **提示**:
|
|
> - macOS 用户需要临时关闭 SIP 才能获取密钥，详见 [macOS 版本说明](../README.md#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**:
|
|
```shell
|
|
docker pull sjzar/chatlog:latest
|
|
```
|
|
|
|
**GitHub Container Registry (ghcr)**:
|
|
```shell
|
|
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 方式
|
|
|
|
**基础部署**:
|
|
```shell
|
|
docker run -d \
|
|
--name chatlog \
|
|
-p 5030:5030 \
|
|
-v /path/to/your/wechat/data:/app/data \
|
|
sjzar/chatlog:latest
|
|
```
|
|
|
|
> 这种部署方式依赖于数据目录下的 chatlog.json 文件作为配置，通过 chatlog 获取密钥时将自动更新 chatlog.json 文件
|
|
|
|
**完整配置示例**:
|
|
```shell
|
|
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 文件**
|
|
|
|
```yaml
|
|
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. 启动服务**
|
|
|
|
```shell
|
|
# 启动服务
|
|
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 示例**:
|
|
```shell
|
|
# 微信 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 示例**:
|
|
```shell
|
|
# 微信 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"
|
|
```
|
|
|
|
### 工作目录
|
|
|
|
工作目录用于存放解密后的数据库文件，可以使用以下两种方式：
|
|
|
|
**本地路径方式**:
|
|
```shell
|
|
-v "/path/to/local/work:/app/work"
|
|
```
|
|
|
|
**命名卷方式**:
|
|
```shell
|
|
-v "chatlog-work:/app/work"
|
|
```
|
|
|
|
|
|
## 远程同步部署
|
|
|
|
对于需要将 chatlog 服务与微信客户端分离部署的场景，可以通过文件同步工具将微信数据同步到远程服务器，然后在远程服务器上运行 chatlog 服务。这种方式具有以下优势：
|
|
|
|
- **解耦部署**：微信客户端和 chatlog 服务可以运行在不同的设备上
|
|
- **灵活性**：可以在 NAS、VPS 等服务器上统一管理聊天数据
|
|
- **安全性**：避免在个人电脑上长期运行服务
|
|
|
|
文件同步工具这里不做过多推荐，个人使用 [Syncthing](https://github.com/syncthing/syncthing)，其他选择有 [Resilio Sync](https://www.resilio.com/sync/)、[rsync + inotify](https://github.com/RsyncProject/rsync) 等，可以按需选择。
|
|
|
|
#### 配置指南
|
|
|
|
- 本地配置: 同步数据目录(Data Dir)，可设置为仅发送；在首次完整同步文件后，建议将 "rescanIntervalS" 设置为 0，全局扫描较为耗时，且扫描过程中会暂停同步
|
|
- 远程服务器配置: 设置为仅接收，同样建议将 "rescanIntervalS" 设置为 0
|
|
- 使用 Docker / Docker Compose 启动 chatlog，将数据目录映射到容器的 `/app/data` 目录
|
|
- 按需配置 `/app/work` 映射目录，可配置到远程服务器本地路径或命名卷
|
|
- 启动容器后，等待首次解密完成后，即可正常请求 API 或接入 MCP 服务
|
|
|
|
#### 部署注意事项
|
|
|
|
- 千万注意数据安全！chatlog 本身未提供授权机制，一定要确保服务处于安全网络环境中。
|
|
|
|
通过远程同步部署，您可以在保持微信客户端正常使用的同时，将 chatlog 服务部署到更适合的环境中，实现数据处理与日常使用的分离。
|
|
|
|
## 部署验证
|
|
|
|
部署完成后，通过以下方式验证服务是否正常运行：
|
|
|
|
**1. 检查容器状态**
|
|
```shell
|
|
docker ps | grep chatlog
|
|
```
|
|
|
|
**2. 查看服务日志**
|
|
```shell
|
|
docker logs chatlog
|
|
```
|
|
|
|
**3. 访问 HTTP API**
|
|
```shell
|
|
# 检查服务健康状态
|
|
curl http://localhost:5030/api/v1/session
|
|
|
|
# 查看联系人列表
|
|
curl http://localhost:5030/api/v1/contact
|
|
```
|
|
|
|
**4. 访问 MCP 服务**
|
|
```shell
|
|
http://localhost:5030/mcp
|
|
```
|
|
|
|
**5. 访问 Web 界面**
|
|
|
|
在浏览器中打开：http://localhost:5030
|
|
|
|
## 常见问题
|
|
|
|
### 1. 容器启动失败
|
|
|
|
**问题**: 容器启动后立即退出
|
|
|
|
**解决方案**:
|
|
- 检查密钥是否正确：`docker logs chatlog`
|
|
- 确认数据目录挂载路径是否正确
|
|
- 检查环境变量配置是否完整
|
|
|
|
### 2. 无法访问 HTTP 服务
|
|
|
|
**问题**: 浏览器无法访问 http://localhost:5030
|
|
|
|
**解决方案**:
|
|
- 检查端口映射是否正确：`docker port chatlog`
|
|
- 确认防火墙是否允许 5030 端口访问
|
|
- 检查容器内服务是否正常启动
|
|
|
|
### 3. 数据目录权限问题
|
|
|
|
**问题**: 日志显示权限不足或文件无法访问
|
|
|
|
**解决方案**:
|
|
```shell
|
|
# 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 端口已被占用
|
|
|
|
**解决方案**:
|
|
```shell
|
|
# 使用其他端口，如 8080
|
|
docker run -p 8080:5030 ...
|
|
|
|
# 或在 docker-compose.yml 中修改
|
|
ports:
|
|
- "8080:5030"
|
|
```
|
|
|
|
> 💡 **获取更多帮助**: 如遇到其他问题，请查看项目的 [Issues](https://github.com/sjzar/chatlog/issues) 页面或提交新的问题反馈。
|