# 一、导读

```{note}
👤 **这份教程写给谁：**

- **一人公司 / OPC**，想做 **第一个可运行的小程序/网站/APP SaaS**，但不知道从哪一步开始动手的朋友。
- **会用 AI 写点代码**，却卡在 **支付、数据库、域名与证书、服务器部署、CI/CD** 等「上线断点」的朋友。
- 想要 **跟着步骤点、跟着填空配置** 直接做出结果，而不是先啃完一本编程书的朋友。

它不是给程序员看的「项目说明书」，而是 **按工程顺序能照做完** 的操作记录。
```

```{important}
🎯 **教程目标：** 带你跑通 **第一条可上线的小程序（网站/APP同理） SaaS 工程闭环**——先在本地让 `saas-starter`、web-pay、收银台、支付平台回调全部闭环，再完成线上 OBS/CDN 前端、宝塔后端、数据库和 **CodeArts 自动化部署**。
```

```{tip}
🧭 **看不懂这些词也没关系。** 你现在不用先背概念，也不用一次理解所有技术细节。后文会用 **「开一家能线上收款的小店」** 做类比，把每一步的目的、做到怎样算过关讲清楚。你最终要搭出来的是一套 **「能在线收款的小程序生意底座」**：顾客能在小程序里下单付款，你能在后台看到订单和付款状态——后面所有技术名词，本质上都是为完成这件事服务的。
```

## 1.1 先用一句话理解你要完成什么

你最终要完成的是：

> 🎯 让一个小程序或 SaaS 产品，具备 **「用户能付款、系统能记账、你能查订单、服务能在线访问」** 的基础能力。

换成生活里的说法，就是：

- 用户看到商品或服务。
- 用户点击购买。
- 用户进入一个收款页面。
- 用户用微信或支付宝付款。
- 系统知道这笔钱付成功了。
- 你在后台能看到这笔订单。
- 这些页面和服务不是只在你电脑上能看，而是放到网上，别人也能访问。

```{tip}
💡 如果你现在只理解到这里，就已经足够开始读这份文档了。
```

![新增概念图：小程序 SaaS 收款闭环](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-09-011-goal-closed-loop.png)

![先用一句话理解你要完成什么](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-01-goal.png)

## 1.2 你不用一开始就懂所有名词

很多新手看到下面这些词会本能地卡住：

- 域名。
- 云服务器。
- 数据库。
- 对象存储。
- CDN。
- 支付商户资料。
- 密钥。
- 证书。
- 回调地址。
- CI/CD。

这些词后面都会解释。你可以先把它们粗略理解成一套线上小店需要的“基础设施”：


| 技术词       | 先用生活语言理解                          |
| -------------- | ------------------------------------------- |
| 域名         | 店铺门牌号，别人通过它找到你              |
| 云服务器     | 一台长期开机的网上电脑，负责干活          |
| 数据库       | 多个超大EXCEL表，上面记录了账本，记录订单、配置和付款状态等等信息            |
| 对象存储     | 放网页文件和图片的仓库                    |
| CDN          | 让别人打开网页更快的加速网络              |
| 支付商户资料 | 你在微信 / 支付宝开通收款能力所需的资料   |
| 密钥 / 证书  | 支付平台确认“这是你本人”的安全凭证      |
| 回调地址     | 支付成功后，微信 / 支付宝通知你系统的网址 |
| CI/CD        | 自动打包、上传、发布的流水线              |

```{note}
不用急着一次记住。后面每一章会在真正用到它的时候再解释。📌
```

![新增概念图：线上小店基础设施名词地图](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-10-012-terms-map.png)

![你不用一开始就懂所有名词](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-02-terms.png)

## 1.3 最后你会看到什么结果

跟完主流程后，理想结果不是“学会很多术语”，而是看到一条真实链路跑通：

1. 你的小程序或业务页面里有一个“去支付”的入口。
2. 用户点击后，进入统一收银台。
3. 收银台展示金额、订单信息和支付方式。
4. 用户用微信或支付宝完成付款。
5. 支付平台把付款结果通知到你的系统。
6. 系统把订单状态改成“已支付”。
7. 你打开运营后台，能看到这笔订单。
8. 后续你改代码后，可以用线上部署和 CodeArts 流水线减少手工上传。

```{important}
✨ 你可以把这当成第一阶段目标：先跑通一笔真实或测试支付，再谈更多功能。
```

![新增概念图：主流程跑通后的支付链路](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-11-013-result-flow.png)

![最后你会看到什么结果](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-03-result.png)

## 1.4 这份文档会怎么带你走

这份文档按“从不懂到能操作”的顺序安排：


| 阅读顺序               | 你会解决的问题                             |
| ------------------------ | -------------------------------------------- |
| 导读                   | 先知道最终在做什么，不被术语吓住           |
| 项目与工程全景         | 用一笔付款理解整套系统如何协作             |
| 账号、成本与资料准备   | 知道要准备哪些账号、资料和大致成本         |
| 本地环境与项目配置     | 准备本机工具、Redis、ActiveMQ、cloudflared 和配置脚本 |
| 本地跑通 web-pay       | 启动收银台、运营平台、支付网关和运营后端   |
| 本地跑通 SaaS          | 启动 `saas-starter` 前端、后端和业务数据库 |
| 本地支付配置           | 打通商户、应用、AppId/AppSecret,资料齐全时补支付通道 |
| web-pay 线上部署       | 先把统一收银台、运营平台和支付网关部署上线 |
| SaaS 支付验收          | 本地 `saas-starter` 调用线上 web-pay,完成下单、收银台付款和业务状态更新 |
| 排查、代码包与边界     | 出错时知道先查哪里，也知道交付边界         |

```{tip}
建议从头读，不要一开始就跳到命令。很多命令看起来复杂，是因为它们前面的准备还没讲清楚。🗺️
```

![新增概念图：从导读到排查的阅读路线](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-12-014-reading-roadmap.png)

![这份文档会怎么带你走](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-04-roadmap.png)

## 1.5 你需要准备的东西到底是什么

你后面会准备一些账号和资料。先不用马上拥有全部东西，但你要知道它们分别用来做什么：


| 你要准备的东西        | 它解决什么问题                   | 新手可以怎么理解   |
| ----------------------- | ---------------------------------- | -------------------- |
| 域名                  | 让别人通过网址访问你的页面和接口 | 店铺门牌           |
| 云服务器              | 让后端程序一直在线运行           | 网上电脑           |
| 数据库                | 保存订单和配置                   | 账本               |
| OBS / CDN             | 放前端页面，让用户打开更快       | 展示橱窗和快递网络 |
| 微信 / 支付宝商户资料 | 让你具备收款能力                 | 收款账户           |
| SSH 账号              | 登录服务器、上传后端文件         | 进入机房的钥匙     |
| CodeArts              | 自动构建和发布                   | 自动打包发货流水线 |

```{note}
缺少某一项时，不代表你不能继续读。你可以先理解它的作用，等做到对应章节再申请或配置。🧰
```

![新增概念图：上线前准备清单](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-13-015-prep-checklist.png)

![你需要准备的东西到底是什么](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-05-prep.png)

## 1.6 文档交付物是什么

你买到的基础文档不是一个“别人替你完成项目”的服务，而是一套自助操作手册。它会提供：

- 每一步为什么要做。
- 做这一步前要准备什么。
- 到哪里填配置。
- 应该复制哪些命令。
- 做完后应该看到什么结果。
- 出错时优先检查哪里。
- 哪些真实配置不能公开传播。

```{note}
**可选代码包**的价值是节省你整理初始配置、脚本和集成的时间，不是替代你理解整个流程。
```

![新增概念图：文档交付物与代码包定位](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-14-016-deliverables.png)

![文档交付物是什么](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-06-manual.png)

## 1.7 你需要接受的边界

```{warning}
这份教程不是陪跑课，也不是代部署服务。为了避免误解，先把边界说清楚：🚧

- 不承诺你一定赚钱。
- 不承诺你一定上线成功。
- 不替你申请域名、服务器、支付商户。
- 不替你填写真实密码、密钥和证书。
- 不代写完整业务项目。
- 不提供长期一对一答疑。
- 不提供深度定制开发。

⚠️ 你需要自己准备账号、自己填写真实配置、自己对线上环境负责。这听起来有点硬，但它也是一人公司必须补上的基本能力。
```

![新增概念图：教程边界与自主管理责任](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-15-017-boundaries.png)

![你需要接受的边界](https://image-osb.obs.cn-east-3.myhuaweicloud.com/OPC%E5%9B%BE%E5%BA%93/start-here-07-boundaries.png)