项目笔记：Ark-Comms-System (A.C.S) - Waline 评论系统私有化部署与集成SOP

第一部分：后端部署——从云端 Serverless 到私有化容器

1.1 技术选型与演进

• 初步方案 (云函数): 探索了使用阿里云函数计算(FC) 和 腾讯云云函数(SCF) 的 Serverless 方案。
  • 优势: 极低的运维成本和优秀的弹性伸缩。
  • 遇到的问题: 模板不兼容 (serverless init 失败)、云厂商 SDK 版本与 Waline 依赖冲突、以及配置文件格式随 Waline 版本剧烈变化，导致调试困难。
• 最终方案 (Docker 私有化部署): 决定采用官方 Docker 镜像，部署在自己的阿里云 ECS 上。
  • 优势: 环境一致性（解决了“在我这能跑”的问题）、高度可控性、日志追踪明确，并且完美契合了我们学习 DevOps 和云原生技术的目标。

1.2 数据库选型与踩坑

• 初步方案 (阿里云表格存储 Tablestore):
  • 尝试: 配置了实例，创建了数据表。
  • 遭遇重大障碍: 连续遇到 OTSAuthFailed(Request denied by instance ACL policies) 错误。通过编写独立的 Node.js 测试脚本 (test.js)，最终定位并解决了阿里云表格存储的网络管理 (IP白名单) 和 安全策略 (ACL) 问题。
  • 根本性失败: 通过阅读阿里云官方文档，最终确认 Waline 主流镜像【原生不支持】Tablestore，需要进行二次开发。这是项目的一个关键转折点。
• 最终方案 (腾讯云开发 TCB):
  • 优势: Waline 官方原生支持，社区验证充分，免费额度充足，且是国内服务。
  • 操作:
    1. 在腾讯云控制台创建了 TCB 环境，并获取了环境ID、Region、以及 API 密钥 (SecretId, SecretKey)。
    2. 【关键步骤】：在 TCB 数据库中，手动创建了 Waline 需要的三个集合：Waline_Comment, Waline_User, Waline_Counter，并将其权限设置为**“读取全部数据，修改本人数据”**。这一步解决了 Waline 无法自动初始化的问题。
  • 字段名修正: 通过查阅最新文档，将在 docker-compose.yml 中使用的腾讯云环境变量从 TCB_SECRET_ID/KEY 修正为 Waline v2 使用的正确字段 TCB_ID/KEY。

1.3 Docker 容器化部署

• 镜像选择: 最初尝试自构建镜像以解决配置问题，但流程复杂。最终决定使用 Waline 官方发布的最新镜像 walinejs/waline:latest，因为它对环境变量的支持是最好、最标准的。

• 核心配置 (docker-compose.yml):

  • 创建了一个包含 waline 服务的 docker-compose.yml。
  • 网络: 将 Waline 容器加入自定义的 Docker bridge 网络 (blog-network)，以便与 Caddy 反向代理容器进行内部通信。
  • 端口: 不在公网暴露 8360 端口，而是让 Caddy 通过内部网络访问，提升安全性。
  • 环境变量 (environment): 最终放弃了 .env 文件和配置文件挂载 (volumes)，因为它们在调试过程中带来了不确定性。改为在 docker-compose.yml 中，使用 environment: 块，直接、明文地定义了所有必需的环境变量（TYPE=tcb, TCB_*, SITE），实现了最高优先级的配置注入。

• 启动与初始化:

  • 通过 docker-compose up -d 成功启动容器。
  • 访问 http://服务器IP:8360/ui/register，成功注册第一个管理员账号，解决了前端 500: Not initialized 的错误，完成了服务的初始化。

• 后台访问: 确认了 Waline v3 的后台 UI 没有固定侧边栏，通过访问 .../ui/comments 或点击左上角图标的方式进入评论管理。

第二部分：与博客前端及 Authing 的无缝集成

2.1 核心配置 (_config.butterfly.yml)

• 启用评论: 在文章的 Front-matter 中设置 comments: true 作为开启评论的开关。在主题配置的 comments: 块中，设置 use: Waline 来全局指定评论提供商。
• Server URL 配置:
  • 经历了从 10.0.0.55:8360 (缺少协议头) -> http://10.0.0.55:8360 (HTTP协议) -> https://waline.linuxnc.xyz (最终HTTPS域名) 的演进。
  • 关键点: serverURL 必须是一个前端浏览器能够通过公网访问到的、协议与主站一致的绝对URL。

2.2 实现游客评论 + Authing 登录

• Waline Option 配置:

  • login: false: 允许游客评论，同时保留登录按钮。
  • requiredMeta: ['nick', 'mail']: 设置游客评论时，昵称和邮箱为必填项。
  • avatar: 'qq': 开启QQ邮箱自动获取头像昵称的功能。
  • provider:: 添加 Authing 作为第三方登录提供商，并填入从 Authing 应用获取的 appId 和 appDomain。

• 明日方舟化定制:

  • 利用 locale: 配置项，将评论框的所有提示语（placeholder, nick, submit 等）都深度定制为“罗德岛”风格，极大地增强了博客的沉浸感。

2.3 高级互动功能

• 文章反应 (reaction: true): 开启了文章底部的 Emoji “点赞”表态功能，增加了轻量级互动。
• 表情包 (emoji: [...]): 配置了多个来自公共 CDN 的表情包（微博、Bilibili等），丰富了评论表达方式。

最终成果: 成功搭建了一套架构清晰、功能强大的前后端分离评论系统。前端用户体验流畅，支持游客评论和多种社交登录；后端服务稳定运行在私有云服务器的 Docker 容器中，数据安全地存储在高性能的国内云数据库里。整个系统实现了高度的自主可控和个性化定制。