> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud 上的 MongoDB：连接、限制与支持的功能

> Square Cloud 上的托管 MongoDB：连接字符串、带客户端证书的 TLS、独立服务器（无事务和 change streams）、用户角色、内存、profiler 以及常见错误。

一个托管的 MongoDB 服务器：使用客户端证书的 TLS 连接，附带一个可以管理自己的数据库、集合和索引的用户。所有引擎共有的信息（限制、snapshot、Insights）请参阅[数据库概览](https://docs.squarecloud.app/zh/services/databases.md)。

## 连接

从控制台中该数据库的页面复制连接 URL。它的形式如下，其中 `default` 用户针对 `admin` 数据库进行身份验证：

```
mongodb://default:PASSWORD@HOST:PORT
```

MongoDB 要求 **TLS 和客户端证书**。在 **连接** → **SSL/TLS 证书** 中下载 `.pem`，并将其同时作为客户端证书和 CA 传入：`tls=true`、`tlsCertificateKeyFile` 和 `tlsCAFile`。

> [!WARNING]
>
> 如果你在 URL 中加上数据库名（`mongodb://...:PORT/mydb`），驱动会针对 `mydb` 进行身份验证，登录会失败并提示 `Authentication failed`。这种情况下请保留 `authSource=admin`：`mongodb://default:PASSWORD@HOST:PORT/mydb?authSource=admin`。

> [tab] Node.js
>
> ```javascript theme={"system"}
> import { MongoClient } from "mongodb";
>
> // One client for the whole process, created once and reused.
> export const client = new MongoClient(process.env.MONGO_URL, {
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
>   maxPoolSize: 10,
> });
>
> await client.connect();
> const users = client.db("app").collection("users");
> ```

> [tab] Mongoose
>
> ```javascript theme={"system"}
> import mongoose from "mongoose";
>
> await mongoose.connect(process.env.MONGO_URL, {
>   dbName: "app",
>   tls: true,
>   tlsCAFile: "certificate.pem",
>   tlsCertificateKeyFile: "certificate.pem",
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> from pymongo import MongoClient
>
> client = MongoClient(
>     os.environ["MONGO_URL"],
>     tls=True,
>     tlsCAFile="certificate.pem",
>     tlsCertificateKeyFile="certificate.pem",
> )
> db = client["app"]
> ```

> [tab] mongosh
>
> ```bash theme={"system"}
> mongosh "mongodb://default:PASSWORD@HOST:PORT" \
>   --tls --tlsCAFile certificate.pem --tlsCertificateKeyFile certificate.pem
> ```

## 独立服务器

每个数据库都是单个\*\*独立（standalone）\*\*服务器：没有副本集，也没有 oplog，并且无法转换为副本集。这意味着：

| 功能 | 状态 | 你会遇到的错误 |
| :- | :- | :- |
| 多文档事务 | 不可用 | `Transaction numbers are only allowed on a replica set member or mongos` |
| Change streams（`watch()`） | 不可用 | `The $changeStream stage is only supported on replica sets` |
| Prisma 配合 MongoDB | 不支持（Prisma 需要副本集） | |
| 官方驱动和 Mongoose | 支持，但不含事务 | |

单文档写入是原子的：使用 `$inc`、`$push` 或 `$set` 等操作符的更新以及 `findOneAndUpdate`，可以覆盖许多原本需要事务的场景。会以事务方式打开会话的库（例如 Mongoose 的 `connection.transaction()`）会失败，并出现上面的第一个错误。

## 连接数

每个数据库最多接受 256 个同时连接。每个 `MongoClient` 都维护自己的连接池（`maxPoolSize`）**外加 2 个监控连接**，因此请为**每个进程创建一个客户端**并重复使用：每个请求创建一个客户端会很快耗尽连接。**Insights** 选项卡会显示是谁占用着这些打开的连接。

## 你的用户与权限

`default` 用户拥有 `readWriteAnyDatabase` 和 `dbAdminAnyDatabase` 角色。你可以创建和删除数据库、集合和索引，并读取 `db.stats()`、`$collStats`、`explain()` 和 profiler（`system.profile`）。

它不能创建用户或角色，不能运行 `db.serverStatus()`，不能查看其他连接的操作（`currentOp`），也不能运行 `top`、`hostInfo`、`setParameter` 或 `shutdown`。依赖 `serverStatus` 的监控工具无法使用；请改用 `db.stats()`、`$collStats` 和 profiler。

## 内存

MongoDB 根据数据库的 RAM 确定 WiredTiger 缓存的大小：**取（RAM 减去 1 GB）的 50% 与 256 MB 中的较大者**。

| 数据库 RAM | WiredTiger 缓存 |
| :- | :- |
| 1 GB | 256 MB |
| 2 GB | 512 MB |
| 4 GB | 1.5 GB |
| 8 GB | 3.5 GB |

* 该大小在服务器启动时读取：修改 RAM 后请重启数据库。它无法调整。
* 缓存只保存你的查询访问过的数据页和索引页。
* 缓存之外的内存：每个连接约 1 MB、索引构建以及聚合（超过 100 MB 的阶段会溢出到磁盘）。
* 内存分配器会保留已释放的内存以便复用，因此控制台中显示的 RAM 会先上升然后保持在高位。这是正常现象，不是内存泄漏。

## 慢查询

profiler 会把耗时 100 ms 或以上的操作记录到每个数据库的 `system.profile` 集合中（上限 1 MB），**Insights** 选项卡会列出这些操作：

```javascript theme={"system"}
db.system.profile.find().sort({ ts: -1 }).limit(5)
```

对慢查询使用 `explain("executionStats")`，查看它是否使用了索引。

## 存储

MongoDB 会保留最多 200 MB 自己的诊断数据，这部分计入数据库的 10 GB。存储完全写满时，MongoDB 会停止且不会自行恢复：请从控制台启动它，并立即释放空间（删除不需要的集合或索引）。参见[磁盘已满](https://docs.squarecloud.app/zh/platform/troubleshooting/database-performance.md#磁盘已满)。

## Snapshot

MongoDB 的 snapshot 包含所有数据库（包括用户），并经过压缩；大小限制适用于压缩后的导出。由于没有 oplog，在有写入进行时创建的 snapshot 并不对应单一时间点。参见 [snapshot 与恢复](https://docs.squarecloud.app/zh/services/databases.md#snapshot-与恢复)。

## 常见错误

| 信息 | 含义 | 处理方法 |
| :- | :- | :- |
| TLS 握手失败，或立即出现 `MongoServerSelectionError` | 客户端未使用 TLS 或未提供客户端证书进行连接。 | 将 `tls`、`tlsCAFile` 和 `tlsCertificateKeyFile` 设置为 `.pem`。 |
| `Authentication failed` | 密码错误，或 URL 中指定了数据库却没有 `authSource=admin`。 | 检查密码；添加 `authSource=admin`。 |
| `Transaction numbers are only allowed on a replica set member or mongos` | 事务需要副本集。 | 使用单文档原子更新。 |
| `The $changeStream stage is only supported on replica sets` | Change streams 需要副本集。 | 从你自己的代码发出变更通知（例如使用 Redis pub/sub）。 |
| `not authorized on admin to execute command` | 该命令需要用户不具备的角色（`serverStatus`、`createUser`...）。 | 使用 `db.stats()`、`$collStats` 和 profiler。 |

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.