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](https://docs.docker.com/engine/install/)。然后让你的用户可以访问守护进程：

```
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
```

## 其他文档

-   [**Welley CLI** docs/index.md](https://welley.com/zh/administrators/docs/cli/)
-   [**部署服务器** skills/deploy-server/SKILL.md](https://welley.com/zh/administrators/docs/deploy-server-skill/)
-   [**openai.yaml** skills/deploy-server/agents/openai.yaml](https://welley.com/zh/administrators/docs/deploy-server-openai-yaml/)
-   [**DigitalOcean 参考** skills/deploy-server/references/digitalocean.md](https://welley.com/zh/administrators/docs/deploy-server-digitalocean/)