diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..039bb4b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,25 @@
+# Changelog
+
+镜像版本演进说明。每条记录镜像里新增 / 调整了什么，对应 `Dockerfile` 与 `skills/` 目录的变更。
+
+## v1
+1. 安装nodejs 22
+2. 安装opencode
+
+## v2
+1. 安装 uv
+2. 安装 python 3.11
+3. 安装 python 依赖
+
+## v3
+1. 创建python虚拟环境为主环境
+2. 增加python依赖
+
+## v3.1
+1. 安装 ripgrep 搜索工具
+2. 增加 pyspark-sql-guardrails skill
+3. 增加 requirements-analysis skill
+
+## v3.2
+1. 安装git
+2. 增加session信息和模型认证信息持久化挂载
diff --git a/README.md b/README.md
index 109dc2d..ab185d9 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@
 ## 构建
 
 ```bash
-docker build -t opencode-custom:latest .
+docker build -t opencode:latest .
 ```
 
 Dockerfile 为多阶段构建：builder 阶段拉取 Node.js 22 与 Python 3.11，最终镜像只保留运行所需文件。
@@ -20,10 +20,20 @@ Dockerfile 为多阶段构建：builder 阶段拉取 Node.js 22 与 Python 3.11
 ## 运行
 
 ```bash
-docker run --rm -it opencode-custom:latest
+docker run -itd --name opencode -p 14096:4096 \
+    -e OPENCODE_SERVER_PASSWORD=Cupdata123 \
+    -v /root/.config/opencode:/root/.config/opencode \
+    -v /root/.local/share/opencode:/root/.local/share/opencode \
+    -v /root/OpenCode:/root/workspace \
+    opencode:latest \
+    web --hostname 0.0.0.0 --mdns --port 4096 --print-logs --log-level DEBUG
 ```
 
-ENTRYPOINT 为 `opencode`，可直接传入 Claude Code 参数。
+参数说明：
+- `-p 14096:4096` 主机 `14096` 端口映射到容器内 `4096`（opencode web 服务端口）
+- `-e OPENCODE_SERVER_PASSWORD=...` 设置 web 服务登录密码（生产环境请改为强密码并通过 secret 管理）
+- 三个 `-v` 挂载分别持久化 opencode 配置、运行数据、以及工作区文件
+- `web` 子命令以 `0.0.0.0` 监听并启用 mDNS，端口 `4096`，日志级别 DEBUG
 
 ## Skills 概览