ZingerLittleBee · ZingerLittleBee · May 17, 2026 · May 17, 2026 · May 17, 2026 · May 17, 2026
diff --git a/apps/docs/content/docs/cn/agent.mdx b/apps/docs/content/docs/cn/agent.mdx
@@ -157,6 +157,28 @@ SERVERBEE_ENROLLMENT_CODE=YOUR_ONE_TIME_CODE serverbee-agent
 
 当 Agent 能读取稳定的机器标识时，还会在注册请求中携带指纹。相同机器重复注册时会复用原有服务器记录并轮换 token，而不是继续创建新的占位条目。
 
+### 更正错误的注册码
+
+如果安装时把注册码（或 `server_url`）填错了，且 Agent **尚未注册成功**（配置中还没有 `token`），无需重装即可更正。注册码为单次使用，填错或已被消费的码无法重复使用——必要时先到管理面板「设置」页重新生成一个新码，再执行：
+
+```bash
+serverbee config set enrollment_code <新注册码> -y
+# 如果 server_url 也填错了：
+serverbee config set server_url http://your-server-ip:9527 -y
+```
+
+`-y` 会顺带重启 Agent，使其立即用新码重新尝试注册。不加 `-y` 时只写入配置但不重启服务，需再执行 `serverbee restart agent`。
+
+若不确定 Agent 当前状态，直接重跑 Agent 安装即可，它会重写 `agent.toml`：
+
+```bash
+serverbee install agent --method <binary|docker> \
+  --server-url http://your-server-ip:9527 \
+  --enrollment-code <新注册码> -y
+```
+
+如果 Agent **已注册成功**（`agent.toml` 中已有 `token`），注册码便不再使用，无需更正；要把该 Agent 接到另一台 Server，只能用新 Server 的新码重新注册。
+
 ## 配置文件
 
 Agent 默认读取 `/etc/serverbee/agent.toml` 配置文件。

diff --git a/apps/docs/content/docs/cn/configuration.mdx b/apps/docs/content/docs/cn/configuration.mdx
@@ -121,7 +121,7 @@ ServerBee 使用 [figment](https://github.com/SergioBenitez/Figment) 库加载
 | `SERVERBEE_DATABASE__PATH` | `serverbee.db` | SQLite 数据库文件路径（相对于 data_dir） |
 | `SERVERBEE_DATABASE__MAX_CONNECTIONS` | `10` | 数据库连接池最大连接数 |
 | `SERVERBEE_AUTH__SESSION_TTL` | `86400` | Session 有效期（秒），默认 24 小时 |
-| `SERVERBEE_AUTH__SECURE_COOKIE` | `true` | Cookie 的 Secure 标记，开发环境设为 `false` |
+| `SERVERBEE_AUTH__SECURE_COOKIE` | `true` | Cookie 的 Secure 标记。仅当浏览器通过普通 HTTP 访问 ServerBee 时设为 `false`，例如 IP 直连的快速开始安装 |
 | `SERVERBEE_RATE_LIMIT__LOGIN_MAX` | `5` | 15 分钟内每 IP 最大登录尝试次数 |
 | `SERVERBEE_RATE_LIMIT__REGISTER_MAX` | `3` | 15 分钟内每 IP 最大 Agent 注册次数 |
 | `SERVERBEE_UPGRADE__RELEASE_BASE_URL` | `https://github.com/ZingerLittleBee/ServerBee/releases` | Agent 升级 Release 资产的基础 URL |
@@ -211,18 +211,6 @@ session_ttl = 86400
 # 默认: 0
 max_servers = 0
 
-# --- 初始管理员 ---
-[admin]
-# 初始管理员用户名
-# 仅在 users 表为空时生效
-# 默认: "admin"
-username = "admin"
-
-# 初始管理员密码
-# 留空则自动生成随机密码并打印到日志
-# 默认: "" (自动生成)
-password = ""
-
 # --- 速率限制 ---
 [rate_limit]
 # 登录接口速率限制：每 IP 每分钟最大请求数

diff --git a/apps/docs/content/docs/cn/deployment.mdx b/apps/docs/content/docs/cn/deployment.mdx
@@ -240,6 +240,38 @@ sudo journalctl -u serverbee-server --since "1 hour ago"
 
 ## Nginx 反向代理
 
+### 访问地址和 Cookie 配置
+
+先确定一个对外访问地址，并让浏览器地址、Agent `server_url` 和 Cookie 配置保持一致：
+
+| 场景 | 对外地址 | `auth.secure_cookie` | Docker 环境变量 | Agent 地址 |
+|------|----------|----------------------|-----------------|------------|
+| IP 直连，普通 HTTP | `http://203.0.113.10:9527` | `false` | `SERVERBEE_AUTH__SECURE_COOKIE=false` | `http://203.0.113.10:9527` |
+| 域名 + HTTPS 反向代理 | `https://monitor.example.com` | `true` | `SERVERBEE_AUTH__SECURE_COOKIE=true` 或不设置该变量 | `https://monitor.example.com` |
+
+使用域名访问时，需要先添加 DNS `A` 或 `AAAA` 记录指向服务器 IP，再用 Nginx、Caddy 或 Traefik 终止 HTTPS，并把请求反向代理到 ServerBee 的 `127.0.0.1:9527`。
+
+如果你是通过快速开始脚本安装的 Server，脚本会为了 HTTP 直连写入 `auth.secure_cookie = false`。迁移到 HTTPS 前，请修改 `/etc/serverbee/server.toml`：
+
+```toml
+[auth]
+secure_cookie = true
+```
+
+然后重启 Server：
+
+```bash
+sudo systemctl restart serverbee-server
+```
+
+如果 ServerBee 已经通过安装脚本部署，也可以使用内置命令自动完成 Caddy HTTPS 配置：
+
+```bash
+sudo serverbee domain setup --domain monitor.example.com --email admin@example.com -y
+```
+
+该命令会校验域名 DNS 是否解析到当前服务器，安装并配置 Caddy，把 ServerBee 改为只监听 `127.0.0.1:9527`，并把 `auth.secure_cookie` 设置为 `true`。如果 DNS 还没生效，命令会停止并打印需要添加的 `A`/`AAAA` 记录。
+
 ### 基础配置
 
 ```nginx title="/etc/nginx/sites-available/serverbee"
@@ -402,6 +434,10 @@ server_url = "https://monitor.example.com"
 ServerBee 自身不处理 TLS 终止。所有 HTTPS/WSS 加密由前置的反向代理（Nginx/Caddy）处理。这种架构简化了 Server 的实现，同时也便于统一管理证书。
 </Callout>
 
+<Callout type="warn">
+使用 HTTPS 时，请保持 `auth.secure_cookie = true`。设为 `false` 可能仍然可以登录，但会去掉浏览器的 Secure Cookie 保护，不适合生产环境。
+</Callout>
+
 ## 备份与恢复
 
 ### 备份

diff --git a/apps/docs/content/docs/cn/quick-start.mdx b/apps/docs/content/docs/cn/quick-start.mdx
@@ -28,6 +28,8 @@ services:
       - "9527:9527"
     volumes:
       - serverbee-data:/data
+    environment:
+      - SERVERBEE_AUTH__SECURE_COOKIE=false
     restart: unless-stopped
 
 volumes:
@@ -46,14 +48,42 @@ docker compose up -d
 
 启动完成后，打开浏览器访问 `http://your-server-ip:9527` 即可进入管理面板。
 
+<Callout type="info">
+上面的 Compose 示例关闭了 Cookie 的 `Secure` 标记，因为快速开始使用的是普通 HTTP。迁移到 HTTPS 后，请设置 `SERVERBEE_AUTH__SECURE_COOKIE=true`。
+</Callout>
+
+## 使用 IP 访问还是域名访问
+
+ServerBee 可以直接用服务器 IP 访问，也可以通过域名和反向代理访问。需要额外配置的地方取决于浏览器最终使用的是普通 HTTP 还是 HTTPS。
+
+| 访问方式 | 浏览器地址 | Server Cookie 配置 | Agent `server_url` | 额外配置 |
+|----------|------------|--------------------|--------------------|----------|
+| IP 直连，普通 HTTP | `http://your-server-ip:9527` | `auth.secure_cookie = false` 或 `SERVERBEE_AUTH__SECURE_COOKIE=false` | `http://your-server-ip:9527` | 防火墙放行 `9527` 端口 |
+| 域名 + HTTPS | `https://monitor.example.com` | `auth.secure_cookie = true` 或 `SERVERBEE_AUTH__SECURE_COOKIE=true` | `https://monitor.example.com` | DNS 指向服务器 IP，并在 ServerBee 前面配置 Nginx、Caddy 或 Traefik |
+
+<Callout type="warn">
+如果你先按快速开始使用 HTTP，之后迁移到域名和 HTTPS，请把 `secure_cookie` 改回 `true`，重启 ServerBee，并把已安装 Agent 的 Server 地址更新为新的 `https://` 地址。
+</Callout>
+
+如果你已经有域名，并且 DNS `A` 记录已经指向当前服务器，可以让安装脚本自动配置 Caddy HTTPS：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server \
+  --domain monitor.example.com \
+  --email admin@example.com \
+  -y
+```
+
+脚本会先校验域名是否解析到当前服务器。未解析或解析到其他 IP 时，脚本会停止并提示应添加的 DNS 记录。`--email` 用于 Let's Encrypt 证书通知，可省略。
+
 ## 方式二：安装脚本
 
 适用于 Linux 服务器，一键完成安装、配置和 systemd 服务注册。
 
 **安装 Server：**
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server
+curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/deploy/install.sh | sudo bash -s -- server -y
 ```
 
 安装脚本会自动完成以下操作：
@@ -65,6 +95,14 @@ curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/depl
 5. 创建 systemd service unit
 6. 启动服务并设置开机自启
 
+首次启动时，Server 会自动创建管理员账号并随机生成密码，该密码只会在服务日志中打印一次。使用以下命令查看：
+
+```bash
+sudo journalctl -u serverbee-server | grep -A8 'FIRST-RUN ADMIN CREDENTIALS'
+```
+
+安装脚本会写入 `auth.secure_cookie = false`，保证普通 HTTP 快速开始地址可以在浏览器中正常登录。迁移到 HTTPS 后，请在 `/etc/serverbee/server.toml` 中改回 `true` 并重启 Server。
+
 **安装 Agent：**
 
 在需要监控的每台服务器上执行：
@@ -89,14 +127,21 @@ sudo serverbee uninstall agent      # 卸载 Agent
 sudo serverbee uninstall server --purge   # 卸载服务端并清除数据
 ```
 
+验证 Server 是否运行：
+
+```bash
+sudo serverbee status
+sudo journalctl -u serverbee-server -n 80 --no-pager
+```
+
 ## 首次登录
 
 1. 打开浏览器访问 `http://your-server-ip:9527`
-2. 使用默认账户 `admin` 和你设置的密码登录
-3. 如果未设置密码，查看 Server 启动日志获取自动生成的密码
+2. 使用默认账户 `admin` 和 Server 启动日志中的随机密码登录
+3. 首次登录时按页面提示完成强制密码修改，可同时选择新的用户名
 
 <Callout type="warn">
-首次登录后请立即修改默认密码。进入「设置」页面即可修改。
+自动生成的密码只会在日志中显示一次。请在日志轮转前复制，并在暴露到公网前完成首次密码修改。
 </Callout>
 
 ## 添加第一台 Agent
@@ -121,6 +166,13 @@ curl -fsSL https://raw.githubusercontent.com/ZingerLittleBee/ServerBee/main/depl
 
 脚本会自动检测平台架构、下载对应二进制、写入配置、注册 systemd 服务并启动 Agent。
 
+验证 Agent 是否已连接并开始上报：
+
+```bash
+sudo serverbee status
+sudo journalctl -u serverbee-agent -n 80 --no-pager
+```
+
 更多采集、日志等可调选项请参考 [Agent 配置](/cn/docs/agent)和[完整配置参考](/cn/docs/configuration)。
 
 首次启动时，Agent 会自动向 Server 注册：注册码在首次注册成功时即被消费，Agent 获取每台服务器专属的 Token 并写回配置文件。后续启动改用持久化的 Token，无需再提供注册码。如果某个 Agent 丢失了 Token 需要重新接入，请在设置页重新生成一个新的注册码。

diff --git a/apps/docs/content/docs/cn/server.mdx b/apps/docs/content/docs/cn/server.mdx
@@ -60,10 +60,6 @@ max_connections = 10
 session_ttl = 86400
 max_servers = 0
 
-[admin]
-username = "admin"
-password = ""
-
 [rate_limit]
 login_max = 5
 register_max = 3
@@ -106,13 +102,6 @@ file = ""
 | `session_ttl` | int | `86400` | Session 过期时间，单位秒（默认 24 小时） |
 | `max_servers` | int | `0` | 通过注册码接入允许创建的新服务器软上限（0 表示不限制） |
 
-#### `[admin]` 初始管理员
-
-| 配置项 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `username` | string | `"admin"` | 初始管理员用户名 |
-| `password` | string | `""` | 初始管理员密码，留空则自动生成随机密码 |
-
 #### `[rate_limit]` 速率限制
 
 | 配置项 | 类型 | 默认值 | 说明 |

diff --git a/apps/docs/content/docs/en/agent.mdx b/apps/docs/content/docs/en/agent.mdx
@@ -118,6 +118,28 @@ enrollment_code = "<one-time code from Settings>"
 
 When the agent can read a stable machine identifier, it also sends a fingerprint during registration. Repeated registration from the same machine reuses the existing server row instead of creating duplicate placeholders. If a code is lost, expired, or already used, the server responds with HTTP 401 and the agent logs `Registration failed: HTTP 401 ... enrollment code ... expired or already used`; mint a fresh code in Settings to retry.
 
+### Correcting a Wrong Enrollment Code
+
+If the agent was installed with a mistyped enrollment code (or wrong `server_url`) and has **not yet registered** (no `token` saved), fix it without reinstalling. Enrollment codes are single-use, so a typo'd or already-consumed code cannot be reused — generate a fresh one in **Settings** first if needed, then:
+
+```bash
+serverbee config set enrollment_code <new-code> -y
+# if the server URL was also wrong:
+serverbee config set server_url http://your-server-ip:9527 -y
+```
+
+The `-y` flag restarts the agent so it retries registration immediately. Without `-y` the value is written but the service is not restarted; run `serverbee restart agent` afterwards.
+
+If you are unsure of the agent's state, simply re-run the agent installer — it rewrites `agent.toml`:
+
+```bash
+serverbee install agent --method <binary|docker> \
+  --server-url http://your-server-ip:9527 \
+  --enrollment-code <new-code> -y
+```
+
+Once the agent has **already registered** (a `token` is present in `agent.toml`), the enrollment code is no longer used and does not need correcting; point the agent at a different server only by re-registering with a fresh code from that server.
+
 ### Manual Token
 
 If you prefer not to use enrollment codes, you can manually create a server entry in the dashboard and provide the token directly:

diff --git a/apps/docs/content/docs/en/configuration.mdx b/apps/docs/content/docs/en/configuration.mdx
@@ -115,7 +115,7 @@ There is no admin username/password environment variable. On first start (when n
 | `SERVERBEE_DATABASE__PATH` | `serverbee.db` | SQLite database file path (relative to data_dir) |
 | `SERVERBEE_DATABASE__MAX_CONNECTIONS` | `10` | Maximum database connection pool size |
 | `SERVERBEE_AUTH__SESSION_TTL` | `86400` | Session token TTL in seconds (default 24h) |
-| `SERVERBEE_AUTH__SECURE_COOKIE` | `true` | Set Secure flag on session cookies. Set `false` for HTTP-only dev |
+| `SERVERBEE_AUTH__SECURE_COOKIE` | `true` | Set the Secure flag on session cookies. Use `false` only when the browser accesses ServerBee over plain HTTP, such as direct IP quick-start installs |
 | `SERVERBEE_RATE_LIMIT__LOGIN_MAX` | `5` | Max login attempts per IP within 15-minute window |
 | `SERVERBEE_RATE_LIMIT__REGISTER_MAX` | `3` | Max agent registrations per IP within 15-minute window |
 | `SERVERBEE_UPGRADE__RELEASE_BASE_URL` | `https://github.com/ZingerLittleBee/ServerBee/releases` | Base URL for agent upgrade release assets |
@@ -182,14 +182,7 @@ Agent top-level keys use single underscore. Nested keys use `__` (double undersc
 |-----|------|---------|-------------|
 | `session_ttl` | i64 | `86400` | Session cookie lifetime in seconds (24 hours) |
 | `max_servers` | u32 | `0` | Maximum servers allowed via enrollment (0 = no limit). Best-effort soft cap |
-| `secure_cookie` | bool | `true` | Set the `Secure` flag on session cookies. Disable only for HTTP-only development |
-
-### `[admin]` -- Initial Admin Account
-
-| Key | Type | Default | Description |
-|-----|------|---------|-------------|
-| `username` | string | `"admin"` | Admin username (used only on first startup when no users exist) |
-| `password` | string | `""` | Admin password. If empty, a random password is generated and logged |
+| `secure_cookie` | bool | `true` | Set the `Secure` flag on session cookies. Use `false` only when the browser accesses ServerBee over plain HTTP |
 
 ### `[retention]` -- Data Retention
 
@@ -357,11 +350,11 @@ The log level can also be set via the `RUST_LOG` environment variable, which tak
 ## Example: Minimal Server Configuration
 
 ```toml
-[admin]
-password = "my-secure-password"
+[server]
+data_dir = "./data"
 ```
 
-Everything else uses sensible defaults. This is sufficient to start a working server that listens on port 9527 with a SQLite database in `./data/`.
+Everything else uses sensible defaults. On first startup, ServerBee creates the `admin` user with a random password and prints it once in the server logs.
 
 ## Example: Production Server Configuration
 
@@ -370,10 +363,6 @@ Everything else uses sensible defaults. This is sufficient to start a working se
 listen = "127.0.0.1:9527"
 data_dir = "/var/lib/serverbee"
 
-[admin]
-username = "admin"
-password = "a-very-strong-password"
-
 [auth]
 secure_cookie = true
 

diff --git a/apps/docs/content/docs/en/deployment.mdx b/apps/docs/content/docs/en/deployment.mdx
@@ -232,6 +232,38 @@ See the [Agent Setup](/en/docs/agent) guide for a complete systemd service unit
 
 Running ServerBee behind a reverse proxy is strongly recommended for production. It provides TLS termination, HTTP/2, and additional security headers.
 
+### Access URL and Cookie Settings
+
+Choose one public access URL and keep the browser URL, agent `server_url`, and cookie setting aligned:
+
+| Scenario | Public URL | `auth.secure_cookie` | Docker Environment Variable | Agent URL |
+|----------|------------|----------------------|-----------------------------|-----------|
+| Direct IP over HTTP | `http://203.0.113.10:9527` | `false` | `SERVERBEE_AUTH__SECURE_COOKIE=false` | `http://203.0.113.10:9527` |
+| Domain through HTTPS reverse proxy | `https://monitor.example.com` | `true` | `SERVERBEE_AUTH__SECURE_COOKIE=true` or omit the variable | `https://monitor.example.com` |
+
+For domain access, create a DNS `A` or `AAAA` record pointing to the server, terminate HTTPS in Nginx, Caddy, or Traefik, and proxy traffic to ServerBee on `127.0.0.1:9527`.
+
+If you installed with the quick-start script, it writes `auth.secure_cookie = false` for direct HTTP access. Before switching that same installation to HTTPS, update `/etc/serverbee/server.toml`:
+
+```toml
+[auth]
+secure_cookie = true
+```
+
+Then restart the server:
+
+```bash
+sudo systemctl restart serverbee-server
+```
+
+If ServerBee was installed with the install script, you can also let the CLI configure Caddy HTTPS automatically:
+
+```bash
+sudo serverbee domain setup --domain monitor.example.com --email admin@example.com -y
+```
+
+This command verifies that the domain resolves to the current server, installs and configures Caddy, changes ServerBee to listen only on `127.0.0.1:9527`, and sets `auth.secure_cookie = true`. If DNS is not ready yet, it stops and prints the `A`/`AAAA` record you need to add.
+
 ### Nginx
 
 ```nginx
@@ -355,7 +387,7 @@ server_url = "https://monitor.example.com"
 The agent automatically handles WebSocket connections using the provided URL.
 
 <Callout type="warn">
-When using HTTPS, ensure `auth.secure_cookie = true` in your server configuration (this is the default). If you set it to `false`, session cookies will not be sent over HTTPS connections, breaking browser authentication.
+When using HTTPS, keep `auth.secure_cookie = true` in your server configuration. Leaving it `false` may still allow login, but it removes the browser's Secure cookie protection and is not appropriate for production.
 </Callout>
 
 ## Backup and Restore