docs/quick-start.md

快速开始：最小化 Welley 部署

这是在单台 Linux 主机上运行 Welley 实例的最短路径，云服务器或你自己的硬件都可以。它只用 CLI 实际要求的参数，其余一律保持默认。

你会得到：平台本身、RAG 流水线、Nginx、Redis，以及一个内置的 PostgreSQL 容器，并在安装过程中签发 Let's Encrypt 证书。这里没有托管数据库，没有 CDN，也没有遥测或 Slack 集成。这些请参考 AWS EC2 和 DigitalOcean 指南。

1. 前提条件

一台 Linux 主机

  • Ubuntu 24.04 LTS（或较新的同类发行版）。
  • 起步配置：2 vCPU、4 GB 内存、60 GB 磁盘。
  • 一个不会变化的公网 IPv4 地址。
  • 对互联网开放入站 TCP 80 和 443 端口，并对你自己开放 22 端口。安装时需要 80 端口来完成证书验证，之后每周续期也要用到它。
  • 一个有 sudo 权限的非 root 用户。本指南的所有操作都用这个用户执行，下文记作 <user>。

DNS

需要两条记录，都指向主机的公网 IP：

记录 用途
<domain> 站点本身
storage.<domain> 上传文件和静态文件，因为这套配置没有 CDN

请在开始之前创建好它们：CLI 会检查这两个域名是否都解析到这台主机，如果没有，就会停止。

邮件 DNS 记录

--smtp-from 地址所在的域名需要配置邮件验证记录。没有这些记录，Gmail、Outlook 等大型邮箱服务常常会丢弃发给从未收到过你邮件的收件人的邮件。这包括每一封邀请和注册确认邮件，而且邮件连垃圾邮件箱都进不去，但你的 SMTP 服务商仍会显示已发送。

记录 类型 值
<mail-domain> TXT SPF，例如 v=spf1 include:<provider> ~all，具体的值请以你的 SMTP 服务商提供的为准
_dmarc.<mail-domain> TXT DMARC，例如 v=DMARC1; p=none; rua=mailto:dmarc@<mail-domain>
<selector>._domainkey.<mail-domain> TXT 或 CNAME DKIM，在你验证域名时由 SMTP 服务商生成

一个域名只能有一条 SPF 记录。如果已经有了，请把你的服务商加到这条记录里，不要再建第二条。如果缺少 SPF 或 DMARC，create 会给出警告，但不会停止。它无法检查 DKIM，因为 selector 名称取决于你的服务商。

不要跳过 DKIM。很多服务商（包括 Amazon SES）默认用自己的域名作为信封发件人。这时 SPF 检查的是服务商的域名，而不是你的，所以它不计入 DMARC，只有 DKIM 才能让 DMARC 通过。请在服务商的控制台里查看 DKIM 状态。在 Amazon SES 中，打开 Verified identities，选择 <mail-domain>，再看 DKIM 一栏，状态必须是 Successful。SES Easy DKIM 会发布三条名为 <token>._domainkey.<mail-domain> 的 CNAME 记录。

SMTP 凭据

主机、用户、密码和发件地址，任何服务商的都可以。平台需要它们来做邮箱确认和密码找回，没有它们 CLI 会拒绝安装。默认按 587 端口的 STARTTLS 提交方式处理。

一个管理员邮箱地址，用于首次登录和密码找回。

2. 安装 Docker

请按你所用发行版的官方说明操作：Install Docker Engine。然后让你的用户可以访问守护进程：

sudo usermod -aG docker <user>

退出登录后重新登录，再确认这两部分都已就绪：

docker ps
docker compose version

3. 下载 CLI

选择与你的主机相符的 platform 值：

linux/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/amd64" -o wlycli
chmod +x wlycli
./wlycli -v
linux/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=linux/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/arm64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/arm64" -o wlycli
chmod +x wlycli
./wlycli -v
darwin/amd64 

curl -fL "https://appstore.allroads.social/v1/social.wellesley.wlycli/latest?channel=stable&platform=darwin/amd64" -o wlycli
chmod +x wlycli
./wlycli -v

4. 部署

./wlycli deploy create \
-d example.com \
-e admin@example.com \
--smtp-host smtp.example.com \
--smtp-user "$MAIL_USER" \
--smtp-password "$MAIL_PASSWORD" \
--smtp-from noreply@example.com

这六个参数就是全部必填项。该命令会检查 DNS、写入部署文件、用 Certbot 签发证书并启动容器，预计需要几分钟。

你在这里接受的默认设置：

设置 默认值
安装目录 ~/.welley/<project>，其中 <project> 是把域名中所有非字母数字字符替换成 _ 后的结果（所以 example.com 会变成 example_com）
数据库 内置的 PostgreSQL 容器，数据放在安装目录下
证书 通过 Certbot 获取 Let's Encrypt 证书，每周自动续期一次
上传文件和静态文件 由 https://storage.<domain> 提供
更新 stable 频道，每天检查一次，尽可能零停机应用

5. 首次登录

生成的管理员密码会输出到平台日志中：

docker logs example_com-platform-blue-1 | grep "Auto-init complete"

打开 https://<domain>，用你通过 -e 传入的管理员邮箱登录，并立即修改密码。在改好之前，请把这份日志当作机密。

6. 检查结果

docker ps

你应该能看到 nginx、platform-blue、rag-pipeline-blue、postgres、redis、autoheal 和 snoopy 各一个容器，名称都是 <project>-<service>-1 的形式。

出了问题怎么办

只要项目目录或其中的容器还在，create 就不会再运行第二次。如果文件没有问题，只是部分容器没能启动，可以重新创建这些容器，不会丢失任何数据：

./wlycli deploy restart -d example.com

如果需要重做整个部署，请先删除再重新开始。这会把内置数据库和其他所有内容一起删除：

./wlycli deploy delete -d example.com --yes-please-delete-all-the-data

其他文档