diff --git a/.goreleaser.yaml b/.goreleaser.yaml
index 3f1bb4e..121ccbd 100644
--- a/.goreleaser.yaml
+++ b/.goreleaser.yaml
@@ -96,6 +96,8 @@ dockers:
       - "ghcr.io/sjzar/chatlog:{{ .Tag }}-amd64"
       - "sjzar/chatlog:{{ .Tag }}-amd64"
     dockerfile: Dockerfile
+    extra_files:
+      - script/docker-entrypoint.sh
     use: buildx
     goos: linux
     goarch: amd64
@@ -114,6 +116,8 @@ dockers:
       - "ghcr.io/sjzar/chatlog:{{ .Tag }}-arm64"
       - "sjzar/chatlog:{{ .Tag }}-arm64"
     dockerfile: Dockerfile
+    extra_files:
+      - script/docker-entrypoint.sh
     use: buildx
     goos: linux
     goarch: arm64
diff --git a/Dockerfile b/Dockerfile
index 142fcb8..2b7adec 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -4,22 +4,31 @@ LABEL maintainer="Sarv <https://github.com/sjzar>"
 
 ARG DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends ca-certificates tzdata curl && \
-    rm -rf /var/lib/apt/lists/*
-
-RUN groupadd -r -g 1001 chatlog && \
-    useradd -r -u 1001 -g chatlog -m -d /home/chatlog chatlog && \
-    mkdir -p /app/data /app/work && \
-    chown -R chatlog:chatlog /app
-
-USER chatlog
+ENV PUID=1000 PGID=1000
+ENV GOSU_VERSION=1.17
+RUN set -eux; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends ca-certificates tzdata curl wget; \
+    wget -O /usr/local/bin/gosu "https://github.com/tianon/gosu/releases/download/$GOSU_VERSION/gosu-$(dpkg --print-architecture)"; \
+	chmod +x /usr/local/bin/gosu; \
+	gosu --version; \
+    groupadd -r -g ${PGID} chatlog; \
+    useradd -r -u ${PUID} -g chatlog -m -d /home/chatlog chatlog; \
+    mkdir -p /app/data /app/work; \
+    apt-get purge -y --auto-remove wget; \
+	rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
 
-COPY --from=mwader/static-ffmpeg:7.1.1 --chown=chatlog:chatlog /ffmpeg /usr/local/bin/
+COPY script/docker-entrypoint.sh /usr/local/bin/entrypoint.sh
 
-COPY --chown=chatlog:chatlog chatlog /usr/local/bin/chatlog
+COPY --from=mwader/static-ffmpeg:7.1.1 /ffmpeg /usr/local/bin/
+
+COPY chatlog /usr/local/bin/chatlog
+
+RUN chmod +x /usr/local/bin/entrypoint.sh \
+             /usr/local/bin/ffmpeg \
+             /usr/local/bin/chatlog
 
 EXPOSE 5030
 
@@ -31,4 +40,6 @@ ENV CHATLOG_DATA_DIR=/app/data \
 HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
     CMD curl -f http://localhost:5030/health || exit 1
 
+ENTRYPOINT ["entrypoint.sh"]
+
 CMD ["chatlog", "server"]
\ No newline at end of file
diff --git a/README.md b/README.md
index 8ca2916..81bcc87 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,31 @@
 <div align="center">
 
-# Chatlog
-
-![chatlog](https://socialify.git.ci/sjzar/chatlog/image?font=Rokkitt&forks=1&issues=1&name=1&pattern=Diagonal+Stripes&stargazers=1&theme=Auto)
+![chatlog](https://github.com/user-attachments/assets/e085d3a2-e009-4463-b2fd-8bd7df2b50c3)
 
 _聊天记录工具，帮助大家轻松使用自己的聊天数据_
 
+[![ImgMCP](https://cdn.imgmcp.com/imgmcp-logo-small.png)](https://imgmcp.com)
+
 [![Go Report Card](https://goreportcard.com/badge/github.com/sjzar/chatlog)](https://goreportcard.com/report/github.com/sjzar/chatlog)
 [![GoDoc](https://godoc.org/github.com/sjzar/chatlog?status.svg)](https://godoc.org/github.com/sjzar/chatlog)
 [![GitHub release](https://img.shields.io/github/release/sjzar/chatlog.svg)](https://github.com/sjzar/chatlog/releases)
 [![GitHub license](https://img.shields.io/github/license/sjzar/chatlog.svg)](https://github.com/sjzar/chatlog/blob/main/LICENSE)
 
-</div>
 
-![chatlog](https://github.com/user-attachments/assets/e085d3a2-e009-4463-b2fd-8bd7df2b50c3)
+</div>
 
 ## Feature
 
-- 从本地数据库文件获取聊天数据
-- 支持 Windows / macOS 系统
-- 支持微信 3.x / 4.0 版本
-- 提供 Terminal UI 界面 & 命令行工具
-- 提供 HTTP API 服务，支持查询聊天记录、联系人、群聊、最近会话等信息
-- 支持 MCP SSE 协议，可与支持 MCP 的 AI 助手无缝集成
-- 支持多媒体消息，支持解密图片、语音
-- 支持自动解密数据，简化使用流程
+- 从本地数据库文件中获取聊天数据
+- 支持 Windows / macOS 系统，兼容微信 3.x / 4.x 版本
+- 支持获取数据与图片密钥 (Windows < 4.0.3.36 / macOS < 4.0.3.80)
+- 支持图片、语音等多媒体数据解密，支持 wxgf 格式解析
+- 支持自动解密数据库，并提供新消息 Webhook 回调
+- 提供 Terminal UI 界面，同时支持命令行工具和 Docker 镜像部署
+- 提供 HTTP API 服务，可轻松查询聊天记录、联系人、群聊、最近会话等信息
+- 支持 MCP Streamable HTTP 协议，可与 AI 助手无缝集成
 - 支持多账号管理，可在不同账号间切换
 
-
-## TODO
-
-- 聊天数据全文索引
-- 聊天数据统计 & Dashboard
-
 ## Quick Start
 
 ### 基本步骤
@@ -43,13 +36,14 @@ _聊天记录工具，帮助大家轻松使用自己的聊天数据_
 4. **开启 HTTP 服务**：选择 `开启 HTTP 服务` 菜单项
 5. **访问数据**：通过 [HTTP API](#http-api) 或 [MCP 集成](#mcp-集成) 访问聊天记录
 
-> 💡 **提示**：如果电脑端微信聊天记录不全，可以[从手机端迁移数据](#从手机迁移聊天记录)
+> 💡 **提示**: 如果电脑端微信聊天记录不全，可以[从手机端迁移数据](#从手机迁移聊天记录)  
 
 ### 常见问题快速解决
 
 - **macOS 用户**：获取密钥前需[临时关闭 SIP](#macos-版本说明)
 - **Windows 用户**：遇到界面显示问题请[使用 Windows Terminal](#windows-版本说明)
 - **集成 AI 助手**：查看 [MCP 集成指南](#mcp-集成)
+- **无法获取密钥**：查看 [FAQ](https://github.com/sjzar/chatlog/issues/197)
 
 ## 安装指南
 
@@ -59,6 +53,8 @@ _聊天记录工具，帮助大家轻松使用自己的聊天数据_
 go install github.com/sjzar/chatlog@latest
 ```
 
+> 💡 **提示**: 部分功能有 cgo 依赖，编译前需确认本地有 C 编译环境。
+
 ### 下载预编译版本
 
 访问 [Releases](https://github.com/sjzar/chatlog/releases) 页面下载适合您系统的预编译版本。
@@ -94,6 +90,49 @@ chatlog decrypt
 chatlog server
 ```
 
+### Docker 部署
+
+由于 Docker 部署时，程序运行环境与宿主机隔离，所以不支持获取密钥等操作，需要提前获取密钥数据。
+
+一般用于 NAS 等设备部署，详细指南可参考 [Docker 部署指南](docs/docker.md)
+
+**0. 获取密钥信息**
+
+```shell
+# 从本机运行 chatlog 获取密钥信息
+$ chatlog key
+Data Key: [c0163e***ac3dc6]
+Image Key: [38636***653361]
+```
+
+**1. 拉取镜像**
+
+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
+
+**2. 运行容器**
+
+```shell
+$ docker run -d \
+  --name chatlog \
+  -p 5030:5030 \
+  -v /path/to/your/wechat/data:/app/data \
+  sjzar/chatlog:latest
+```
+
 ### 从手机迁移聊天记录
 
 如果电脑端微信聊天记录不全，可以从手机端迁移数据：
@@ -173,23 +212,101 @@ GET /api/v1/chatlog?time=2023-01-01&talker=wxid_xxx
 当请求语音内容时，将直接返回语音内容，并对原始 SILK 语音做了实时转码 MP3 处理。  
 多媒体内容 URL 地址为基于`数据目录`的相对地址，请求多媒体内容将直接返回对应文件，并针对加密图片做了实时解密处理。
 
+## Webhook
+
+需开启自动解密功能，当收到特定新消息时，可以通过 HTTP POST 请求将消息推送到指定的 URL。
+
+#### 0. 回调配置
+
+使用 TUI 模式的话，在 `$HOME/.chatlog/chatlog.json` 配置文件中，新增 `webhook` 配置。  
+（Windows 用户的配置文件在 `%USERPROFILE%/.chatlog/chatlog.json`)
+
+```json
+{
+  "history": [],
+  "last_account": "wxuser_x",
+  "webhook": {
+    "host": "localhost:5030",                   # 消息中的图片、文件等 URL host
+    "items": [
+      {
+        "url": "http://localhost:8080/webhook", # 必填，webhook 请求的URL，可配置为 n8n 等 webhook 入口 
+        "talker": "wxid_123",                   # 必填，需要监控的私聊、群聊名称
+        "sender": "",                           # 选填，消息发送者
+        "keyword": ""                           # 选填，关键词
+      }
+    ]
+  }
+}
+```
+
+使用 server 模式的话，可以通过 `CHATLOG_WEBHOOK` 环境变量进行设置。
+
+```shell
+# 方案 1
+CHATLOG_WEBHOOK='{"host":"localhost:5030","items":[{"url":"http://localhost:8080/proxy","talker":"wxid_123","sender":"","keyword":""}]}'
+
+# 方案 2（任选一种）
+CHATLOG_WEBHOOK_HOST="localhost:5030"
+CHATLOG_WEBHOOK_ITEMS='[{"url":"http://localhost:8080/proxy","talker":"wxid_123","sender":"","keyword":""}]'
+```
+
+#### 1. 测试效果
+
+启动 chatlog 并开启自动解密功能，测试回调效果
+
+```shell
+POST /webhook HTTP/1.1
+Host: localhost:8080
+Accept-Encoding: gzip
+Content-Length: 386
+Content-Type: application/json
+User-Agent: Go-http-client/1.1
+
+Body:
+{
+  "keyword": "",
+  "lastTime": "2025-08-27 00:00:00",
+  "length": 1,
+  "messages": [
+    {
+      "seq": 1756225000000,
+      "time": "2025-08-27T00:00:00+08:00",
+      "talker": "wxid_123",
+      "talkerName": "",
+      "isChatRoom": false,
+      "sender": "wxid_123",
+      "senderName": "Name",
+      "isSelf": false,
+      "type": 1,
+      "subType": 0,
+      "content": "测试消息",
+      "contents": {
+        "host": "localhost:5030"
+      }
+    }
+  ],
+  "sender": "",
+  "talker": "wxid_123"
+}
+```
+
 ## MCP 集成
 
-Chatlog 支持 MCP (Model Context Protocol) SSE 协议，可与支持 MCP 的 AI 助手无缝集成。  
-启动 HTTP 服务后，通过 SSE Endpoint 访问服务：
+Chatlog 支持 MCP (Model Context Protocol) 协议，可与支持 MCP 的 AI 助手无缝集成。  
+启动 HTTP 服务后，通过 Streamable HTTP Endpoint 访问服务：
 
 ```
-GET /sse
+GET /mcp
 ```
 
 ### 快速集成
 
 Chatlog 可以与多种支持 MCP 的 AI 助手集成，包括：
 
-- **ChatWise**: 直接支持 SSE，在工具设置中添加 `http://127.0.0.1:5030/sse`
-- **Cherry Studio**: 直接支持 SSE，在 MCP 服务器设置中添加 `http://127.0.0.1:5030/sse`
+- **ChatWise**: 直接支持 Streamable HTTP，在工具设置中添加 `http://127.0.0.1:5030/mcp`
+- **Cherry Studio**: 直接支持 Streamable HTTP，在 MCP 服务器设置中添加 `http://127.0.0.1:5030/mcp`
 
-对于不直接支持 SSE 的客户端，可以使用 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) 工具转发请求：
+对于不直接支持 Streamable HTTP 的客户端，可以使用 [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) 工具转发请求：
 
 - **Claude Desktop**: 通过 mcp-proxy 支持，需要配置 `claude_desktop_config.json`
 - **Monica Code**: 通过 mcp-proxy 支持，需要配置 VSCode 插件设置
diff --git a/docs/docker.md b/docs/docker.md
new file mode 100644
index 0000000..6a37f49
--- /dev/null
+++ b/docs/docker.md
@@ -0,0 +1,357 @@
+# 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)，可设置为仅发送
+- 远程服务器配置: 设置为仅接收
+- 使用 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) 页面或提交新的问题反馈。
diff --git a/script/docker-entrypoint.sh b/script/docker-entrypoint.sh
new file mode 100644
index 0000000..b812bb3
--- /dev/null
+++ b/script/docker-entrypoint.sh
@@ -0,0 +1,20 @@
+#!/bin/sh
+set -eu
+
+[ -n "${UMASK:-}" ] && umask "$UMASK"
+
+if [ "$(id -u)" = '0' ]; then
+  PUID=${PUID:-1000}
+  PGID=${PGID:-1000}
+
+  DATA_DIRS="/app /usr/local/bin"
+  for DIR in ${DATA_DIRS}; do
+    if [ -d "$DIR" ]; then
+      chown -R "${PUID}:${PGID}" "$DIR" || true
+    fi
+  done
+
+  exec gosu "${PUID}:${PGID}" "$@"
+else
+  exec "$@"
+fi