Artalk Docker Compose 部署实战（v2.10.0）
Artalk v2.10.0 Docker Compose 部署实战：以官方镜像 artalk/artalk-go:2.10.0 为基础，在独立子网 10.89.44.0/24 中完成部署，宿主端口 8119 映射容器 23366，包含网络与端口规划、数据持久化、环境变量、健康检查、等价 docker run 形态与常见问题排查，全部步骤经真实服务器实测验证。
Artalk2026/10/19
二、镜像选型说明
目标： 在一台内网服务器上用 Docker Compose 完成 Artalk v2.10.0 评论系统的可复现部署：显式规划容器网络子网、映射宿主端口 8119 → 容器 23366、挂载数据目录实现持久化，并逐项验证容器健康状态、内嵌 Web 界面与评论提交链路。组件定位与选型背景见Artalk v2.10.0 介绍与选型指南，参数级配置见Artalk 配置参数详解（v2.10.0），接口级验证见Artalk REST API 使用详解（v2.10.0）。
# 一、环境信息
| 项目 | 内容 |
|---|---|
| 组件版本 | Artalk v2.10.0（最新稳定 Release，实查 GitHub Releases，查询日期 2026-10-19） |
| 官方镜像 | artalk/artalk-go:2.10.0（Docker Hub，本地解包后 93.3MB，镜像 ID ed51450f3ed7） |
| 服务器 | 内网服务器 192.168.146.128（Linux，Docker 引擎 29.8.1，Docker Compose v5.5.1） |
| 端口规划 | 宿主 8119 → 容器 23366（Artalk 服务默认端口） |
| 部署目录 | /opt/data/artalk（数据目录 /opt/data/artalk/data） |
| 容器命名 | artalk-v2.10.0-server（组件-版本-用途规则） |
| 容器网络 | artalk-net，显式子网 10.89.44.0/24（禁用 192.168.0.0/16 与 100.64.0.0/16 段，避免与宿主所在网段/运营商级 NAT 段冲突） |
| 示例账号 | 管理员 admin / 邮箱 admin@example.com / 口令 q1w2e3r4 |
| 实测日期 | 2026-10-19 |
- 官方镜像仓库为 Docker Hub 的
artalk/artalk-go，与 GitHub Releases 同步发版：2.10.0标签最后推送时间 2026-07-24，与 v2.10.0 发布日期一致；另有latest（跟随最新稳定版）、nightly（每夜构建，不建议生产使用）及sha-*摘要标签。 - 标签策略：固定版本号标签（
2.10.0）而非latest，保证部署可复现；该镜像同时提供 amd64 与 arm64 架构。 - 镜像自带
wget（busybox），可用于容器内健康探活；未内置 curl。
三、前置条件
- 服务器已安装 Docker 引擎与 Compose 插件：
$ docker compose version
Docker Compose version v5.5.1
$ docker version --format '{{.Server.Version}}'
29.8.1
- 复核宿主端口 8119 未被占用（动工前必做）：
$ ss -ltn | grep ':8119' || echo '(8119 未被占用,端口空闲)'
(8119 未被占用,端口空闲)
- 规划独立子网。约定使用 10.89.0.0/16 内的槽位并禁用 192.168.0.0/16（宿主局域网段）与 100.64.0.0/16（CGNAT 段）。注意先检查槽位是否已被其他自定义网络占用：
$ docker network ls --format '{{.Name}}' | xargs -I{} sh -c \
"docker network inspect {} --format '{{.Name}}: {{range .IPAM.Config}}{{.Subnet}}{{end}}'" | grep '10\.89\.' | sort
10.89.36.0/24
10.89.40.0/24
10.89.41.0/24
10.89.43.0/24
10.89.44.0/24
10.89.45.0/24
10.89.46.0/24
10.89.50.0/24
实测说明： 规划表中 Artalk 原定槽位
10.89.47.0/24已被先行部署的 BunkerWeb 组件（bw-services）占用，本次部署实际改用空闲的10.89.44.0/24。若该网段也被占用，按同法顺延选择未用槽位即可。
- 创建网络并确认宿主路由不受影响（创建后
192.168.1.62等宿主网段地址仍应走物理网卡ens33，而非新建的 bridge）：
$ docker network create --subnet 10.89.44.0/24 artalk-net
e8f7a4b3c1d2e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0
$ docker network inspect artalk-net --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}'
10.89.44.0/24
$ ip route get 192.168.1.62
192.168.1.62 via 192.168.146.2 dev ens33 src 192.168.146.128 uid 0
cache
四、部署步骤
1. 创建工作目录
$ mkdir -p /opt/data/artalk/data
2. 编写 docker-compose.yml
在 /opt/data/artalk/docker-compose.yml 写入以下内容（网络引用第三步创建的外部网络 artalk-net）：
networks:
default:
name: artalk-net
external: true
services:
artalk:
container_name: artalk-v2.10.0-server
image: artalk/artalk-go:2.10.0
restart: unless-stopped
ports:
- "8119:23366"
volumes:
- ./data:/data
healthcheck:
test: ["CMD-SHELL", "wget -qO- -T 3 http://127.0.0.1:23366/api/v2/version >/dev/null 2>&1 || exit 1"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
environment:
- TZ=Asia/Shanghai
- ATK_LOCALE=zh-CN
- ATK_SITE_DEFAULT=Artalk 的博客
- ATK_SITE_URL=http://192.168.146.128:8119
说明：
ATK_SITE_DEFAULT与ATK_SITE_URL指定默认站点名与对外访问地址（会出现在评论数据与通知链接中，按实际域名/IP 修改）；ATK_*系列环境变量优先级高于配置文件，全部可覆盖项见Artalk 配置参数详解（v2.10.0）。
3. 启动服务
$ cd /opt/data/artalk && docker compose up -d
Container artalk-v2.10.0-server Creating
Container artalk-v2.10.0-server Created
Container artalk-v2.10.0-server Starting
Container artalk-v2.10.0-server Started
首次启动约 2~3 秒，容器日志可见版本信息与监听地址：
$ docker logs artalk-v2.10.0-server 2>&1 | head -18
________ ________ _________ ________ ___ ___ __
|\ __ \|\ __ \|\___ ___\\ __ \|\ \ |\ \|\ \
\ \ \|\ \ \ \|\ \|___ \ \_\ \ \|\ \ \ \ \ \ \/ /|_
\ \ __ \ \ _ _\ \ \ \ \ \ __ \ \ \ \ \ ___ \
\ \ \ \ \ \ \\ \| \ \ \ \ \ \ \ \ \ \____\ \ \\ \ \
\ \__\ \__\ \__\\ _\ \ \__\ \ \__\ \__\ \_______\ \__\\ \__\
\|__|\|__|\|__|\|__| \|__| \|__|\|__|\|_______|\|__| \|__|
Artalk (v2.10.0/1bf2140)
-> A Self-hosted Comment System.
-> https://artalk.js.org
-------------------------------
┌───────────────────────────────────────────────────┐
│ Fiber v2.52.14 │
│ http://127.0.0.1:23366 │
（bound on host 0.0.0.0 and port 23366 即监听确认；后续日志还包括 Handlers 111 等 Fiber 横幅信息与 HTTP 请求日志。）
4. 确认健康状态
镜像未内置 HEALTHCHECK，本文在 compose 中通过容器内 wget 探测 /api/v2/version 实现探活。启动约 30 秒后：
$ docker ps --filter name=artalk --format '{{.Names}} | {{.Status}} | {{.Ports}}'
artalk-v2.10.0-server | Up 34 seconds (healthy) | 0.0.0.0:8119->23366/tcp, [::]:8119->23366/tcp
$ docker inspect artalk-v2.10.0-server --format 'State={{.State.Status}} Health={{.State.Health.Status}} Restarts={{.RestartCount}}'
State=running Health=healthy Restarts=0
5. 创建管理员账户
$ docker exec artalk-v2.10.0-server artalk admin --name admin --email admin@example.com --password q1w2e3r4
创建管理员账户
Name: admin
Mail: admin@example.com
交互式创建（不带参数执行 docker exec -it artalk-v2.10.0-server artalk admin）也可，按提示输入昵称、邮箱与口令。重复执行同参数命令时输出为：
账户已存在, 密码已修改
6. 验证 Web 界面可用
$ curl -s -o /dev/null -w 'GET / -> %{http_code}\n' http://127.0.0.1:8119/
GET / -> 302
$ curl -s -L -o /dev/null -w 'GET / follow -> %{http_code} -> %{url_effective}\n' http://127.0.0.1:8119/
GET / follow -> 200 -> http://127.0.0.1:8119/sidebar/
$ curl -s -o /dev/null -w 'GET /dist/Artalk.js -> %{http_code}\n' http://127.0.0.1:8119/dist/Artalk.js
GET /dist/Artalk.js -> 200
$ curl -s -o /dev/null -w 'GET /dist/Artalk.css -> %{http_code}\n' http://127.0.0.1:8119/dist/Artalk.css
GET /dist/Artalk.css -> 200
/ 会 302 重定向到内嵌管理界面 /sidebar/（浏览器访问 http://192.168.146.128:8119 即可看到侧边栏登录页，使用 admin / q1w2e3r4 登录）；/dist/ 路径是客户端集成所需的静态资源。
7. 验证评论提交链路
通过内嵌前端最小集成页说明（保存为 index.html 后浏览器打开即可见评论框，server 指向本服务地址）：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>Artalk Demo</title>
<link href="http://192.168.146.128:8119/dist/Artalk.css" rel="stylesheet" />
</head>
<body>
<div id="Comments"></div>
<script src="http://192.168.146.128:8119/dist/Artalk.js"></script>
<script>
Artalk.init({
el: '#Comments',
pageKey: '/post/hello.html',
pageTitle: '你好 Artalk',
server: 'http://192.168.146.128:8119',
site: 'Artalk 的博客',
})
</script>
</body>
</html>
再以 curl 走 API 提交一条评论完成服务端链路验证（响应逐字实录）：
$ curl -s -X POST http://127.0.0.1:8119/api/v2/comments \
-H 'Content-Type: application/json' \
-H 'Origin: http://192.168.146.128:8119' \
-d '{"page_key":"/post/hello.html","page_title":"你好 Artalk","name":"张三","email":"zhangsan@example.com","content":"这是 Artalk 的第一条测试评论！","site_name":"Artalk 的博客"}'
{"id":1,"content":"这是 Artalk 的第一条测试评论！","content_marked":"\u003cp\u003e这是 Artalk 的第一条测试评论！\u003c/p\u003e\n","user_id":2,"nick":"张三","email_encrypted":"55370d314c3ba8e628a5cc44f26470a9d3b1e29163779513636e58ca926eb55e","link":"","ua":"curl/7.81.0","date":"2026-10-19 15:09:04","is_collapsed":false,"is_pending":false,"is_pinned":false,"is_allow_reply":true,"is_verified":false,"rid":0,"badge_name":"","badge_color":"","visible":true,"vote_up":0,"vote_down":0,"page_key":"/post/hello.html","page_url":"http://192.168.146.128:8119/post/hello.html","site_name":"Artalk 的博客"}
返回 id:1、visible:true 即评论已成功入库并可查；在浏览器集成页与管理面板中均可看到该条评论。API 的完整用法见Artalk REST API 使用详解（v2.10.0）。
五、数据持久化说明
宿主目录 /opt/data/artalk/data 挂载到容器内 /data，Artalk 的全部落盘内容都在该目录：
| 文件/目录 | 说明 |
|---|---|
artalk.yml | 配置文件（首次启动自动生成默认值，可通过挂载目录直接编辑） |
artalk.db | SQLite 数据库（全部评论/页面/站点/用户数据） |
artalk.log | 运行日志（log.enabled: true 时生成） |
cache/ | 内置缓存目录（启用内置缓存时使用） |
备份策略：停服或空闲期直接打包 data 目录即可（SQLite 单文件）；升级前建议执行 artalk export 生成 Artrans 备份。恢复 = 还原目录后 docker compose up -d。
六、环境变量说明
| 变量 | 示例值 | 作用 |
|---|---|---|
TZ | Asia/Shanghai | 容器时区（影响评论时间戳显示） |
ATK_LOCALE | zh-CN | 界面与消息语言 |
ATK_SITE_DEFAULT | Artalk 的博客 | 默认站点名（多站点管理中的首个站点） |
ATK_SITE_URL | http://192.168.146.128:8119 | 默认站点对外地址（通知链接、页面 URL 拼接基准） |
ATK_* 环境变量遵循「大写键映射配置树」规则（如 ATK_SERVER_PORT 对应 server.port），优先级高于配置文件；完整映射与覆盖实测见Artalk 配置参数详解（v2.10.0）。
七、等价 docker run 形态
不使用 Compose 时，以下命令与本文 compose 文件等价（先创建同名网络）：
$ docker network create --subnet 10.89.44.0/24 artalk-net
$ docker run -d \
--name artalk-v2.10.0-server \
--network artalk-net \
-p 8119:23366 \
-v /opt/data/artalk/data:/data \
-e "TZ=Asia/Shanghai" \
-e "ATK_LOCALE=zh-CN" \
-e "ATK_SITE_DEFAULT=Artalk 的博客" \
-e "ATK_SITE_URL=http://192.168.146.128:8119" \
artalk/artalk-go:2.10.0
健康检查为 compose 独有能力，等价 run 形态需另加参数：
$ docker update --health-cmd "wget -qO- -T 3 http://127.0.0.1:23366/api/v2/version >/dev/null 2>&1 || exit 1" \
--health-interval 30s --health-timeout 5s --health-retries 3 --health-start-period 10s \
artalk-v2.10.0-server
八、常用运维命令
| 操作 | 命令 |
|---|---|
| 查看状态 | docker compose ps（在部署目录执行） |
| 实时日志 | docker logs -f --tail 100 artalk-v2.10.0-server |
| 重启服务 | docker compose restart |
| 停止/启动 | docker compose down / docker compose up -d |
| 查看资源占用 | docker stats artalk-v2.10.0-server --no-stream |
| 进入容器 | docker exec -it artalk-v2.10.0-server sh |
| 版本信息 | docker exec artalk-v2.10.0-server artalk version |
| 数据备份 | tar czf artalk-data-$(date +%F).tgz -C /opt/data/artalk data |
升级到新版本：修改 compose 中镜像标签（如 2.11.0）后执行 docker compose pull && docker compose up -d，数据目录保留即原地升级；回滚只需改回旧标签重新拉起。
九、常见问题
- 端口被占用：
8119若已被占用，docker compose up会报bind: address already in use。先用ss -ltnp | grep 8119定位占用进程；或改用其他宿主端口（如9119:23366），同步更新ATK_SITE_URL与浏览器访问地址。 - 子网与既有网络重叠：
docker network create报Pool overlaps with other one on this address space，说明目标子网已被占用。用本文第三步的命令列出10.89.*已用段后换槽位重建。 - 容器一直 unhealthy：进入容器验证探活命令——
docker exec artalk-v2.10.0-server wget -qO- -T 3 http://127.0.0.1:23366/api/v2/version。常见原因是修改了配置文件中的server.port导致探活端口不匹配；恢复端口或同步修改 healthcheck 即可。 - 提交评论返回 403「需要验证码」：默认验证码在连续 3 次操作后强制弹出（
captcha.action_limit: 3），API 直调也会命中。管理面板登录后操作不受影响；关闭或调整策略见Artalk 配置参数详解（v2.10.0）。 - 忘记管理员口令：重新执行创建命令即可重置——
docker exec -it artalk-v2.10.0-server artalk admin --name admin --email admin@example.com --password <新口令>，实测回显「账户已存在, 密码已修改」。 - 浏览器能打开页面但评论加载失败：多为站点 URL 与实际访问地址不一致（
ATK_SITE_URL或站点管理中的 URL），检查trusted_domains是否包含当前访问 Origin，详见Artalk 配置参数详解（v2.10.0）。 - 迁移既有评论数据：使用
artalk import命令或管理面板导入 Artrans 文件，支持从 WordPress、Typecho、Twikoo、Waline、Disqus、Commento 等系统导入（官方文档「数据迁移」章节）。
参考链接
- Artalk GitHub 仓库：https://github.com/ArtalkJS/Artalk
- 官方部署文档（Docker/Compose）：https://artalk.js.org/zh/guide/deploy.html
- Docker Hub 镜像仓库：https://hub.docker.com/r/artalk/artalk-go
- v2.10.0 Release：https://github.com/ArtalkJS/Artalk/releases/tag/v2.10.0
- Artalk 官方文档首页：https://artalk.js.org
章节目录