Skip to content

Commit b478f58

Browse files
hhhhsc701hhhhsc701
authored
Add deployment script guidance for monitoring and OAuth (#3168)
Co-authored-by: hhhhsc <name>
1 parent 9f3d843 commit b478f58

5 files changed

Lines changed: 423 additions & 14 deletions

File tree

‎doc/docs/en/quick-start/installation.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,106 @@ For complete port mapping details, see our [Dev Container Guide](../deployment/d
173173
174174
## 🔧 Advanced Configuration
175175
176+
### Monitoring Configuration
177+
178+
Select the `monitoring` component in the deployment script UI to enable OpenTelemetry monitoring. The script synchronizes `ENABLE_TELEMETRY`, `MONITORING_PROVIDER`, and `MONITORING_DASHBOARD_URL` in `docker/.env`, then starts the matching observability services from `docker/docker-compose-monitoring.yml`.
179+
180+
```bash
181+
cd nexent/docker
182+
bash deploy.sh
183+
```
184+
185+
If `docker/deploy.options` already exists, the script asks whether to reuse local configuration. Choose to reconfigure/overwrite local configuration, then select `monitoring` in the component menu and manually choose `grafana`, `phoenix`, `langfuse`, `langsmith`, `zipkin`, or `otlp` in the provider menu.
186+
187+
Supported providers:
188+
189+
| Provider | Purpose | Default URL |
190+
|----------|---------|-------------|
191+
| `otlp` | OpenTelemetry Collector only, useful for forwarding to an external platform | No dashboard |
192+
| `phoenix` | Local Phoenix trace analysis | `http://localhost:6006` |
193+
| `langfuse` | Local Langfuse observability stack | `http://localhost:3001` |
194+
| `langsmith` | Forwarding to hosted LangSmith | `https://smith.langchain.com/` |
195+
| `grafana` | Local Grafana + Tempo | `http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1` |
196+
| `zipkin` | Local Zipkin | `http://localhost:9411` |
197+
198+
To change ports, image versions, or local Langfuse bootstrap credentials, copy and edit the monitoring environment file first:
199+
200+
```bash
201+
cp docker/monitoring/monitoring.env.example docker/monitoring/monitoring.env
202+
```
203+
204+
Common variables:
205+
206+
| Variable | Description |
207+
|----------|-------------|
208+
| `MONITORING_PROVIDER` | Default monitoring provider; updated when you choose a provider in the deployment script |
209+
| `OTEL_COLLECTOR_HTTP_PORT` / `OTEL_COLLECTOR_GRPC_PORT` | Published OTLP HTTP/gRPC ports |
210+
| `LANGSMITH_API_KEY` / `LANGSMITH_PROJECT` | LangSmith forwarding configuration |
211+
| `LANGFUSE_INIT_USER_EMAIL` / `LANGFUSE_INIT_USER_PASSWORD` | Local Langfuse bootstrap admin |
212+
| `GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD` | Local Grafana admin |
213+
214+
Before choosing the `langsmith` provider, configure `LANGSMITH_API_KEY` in `docker/monitoring/monitoring.env`. If you only need to connect to an existing external Collector, adjust the OTLP target in `docker/.env`:
215+
216+
```bash
217+
ENABLE_TELEMETRY=true
218+
MONITORING_PROVIDER=otlp
219+
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
220+
OTEL_EXPORTER_OTLP_PROTOCOL=http
221+
MONITORING_DASHBOARD_URL=
222+
```
223+
224+
> **Production note**: Replace default passwords, secrets, and the Langfuse `ENCRYPTION_KEY`. Restrict dashboard and Collector access with a reverse proxy or firewall.
225+
226+
### OAuth Login Configuration
227+
228+
OAuth login requires the `supabase` component. When enabling third-party login, deploy `supabase` and set `OAUTH_CALLBACK_BASE_URL` to the browser-accessible Nexent Web URL.
229+
230+
```bash
231+
bash deploy.sh --components infrastructure,application,supabase
232+
```
233+
234+
For Docker, configure OAuth in `docker/.env`:
235+
236+
```bash
237+
# Web entry URL. The full callback path is generated as:
238+
# {OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=<provider>
239+
OAUTH_CALLBACK_BASE_URL=http://localhost:3000
240+
241+
# GitHub OAuth
242+
GITHUB_OAUTH_CLIENT_ID=
243+
GITHUB_OAUTH_CLIENT_SECRET=
244+
245+
# GDE OAuth
246+
GDE_URL=
247+
GDE_OAUTH_CLIENT_ID=
248+
GDE_OAUTH_CLIENT_SECRET=
249+
250+
# Link App OAuth
251+
LINK_APP_URL=
252+
LINK_APP_OAUTH_CLIENT_ID=
253+
LINK_APP_OAUTH_CLIENT_SECRET=
254+
255+
# WeChat OAuth
256+
ENABLE_WECHAT_OAUTH=false
257+
WECHAT_OAUTH_APP_ID=
258+
WECHAT_OAUTH_APP_SECRET=
259+
260+
# TLS verification when contacting OAuth providers
261+
OAUTH_SSL_VERIFY=true
262+
OAUTH_CA_BUNDLE=
263+
```
264+
265+
Provider enablement rules:
266+
267+
| Provider | Required variables | Callback URL |
268+
|----------|--------------------|--------------|
269+
| GitHub | `GITHUB_OAUTH_CLIENT_ID`, `GITHUB_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github` |
270+
| GDE | `GDE_URL`, `GDE_OAUTH_CLIENT_ID`, `GDE_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde` |
271+
| Link App | `LINK_APP_URL`, `LINK_APP_OAUTH_CLIENT_ID`, `LINK_APP_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=link_app` |
272+
| WeChat | `ENABLE_WECHAT_OAUTH=true`, `WECHAT_OAUTH_APP_ID`, `WECHAT_OAUTH_APP_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat` |
273+
274+
For local Docker, a GitHub callback example is `http://localhost:3000/api/user/oauth/callback?provider=github`. In production, use a public HTTPS domain such as `https://nexent.example.com/api/user/oauth/callback?provider=github` and register the exact same URL in the OAuth provider console.
275+
176276
### Northbound Interface Configuration (NORTHBOUND_EXTERNAL_URL)
177277
178278
If you need to use any of the following features, configure the `NORTHBOUND_EXTERNAL_URL` environment variable:

‎doc/docs/en/quick-start/kubernetes-installation.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,102 @@ Helm uninstall does not delete local hostPath data by default. Use `./uninstall.
195195
./uninstall.sh delete-all --keep-local-data
196196
```
197197

198+
## 🔧 Advanced Configuration
199+
200+
### Monitoring Configuration
201+
202+
Kubernetes deployments enable monitoring through the `monitoring` component in the deployment script UI. The deployment script renders runtime Helm values for `global.monitoring.enabled`, `global.monitoring.provider`, and `global.monitoring.dashboardUrl`, and enables the `nexent-monitoring` subchart.
203+
204+
```bash
205+
cd nexent/k8s/helm
206+
./deploy.sh
207+
```
208+
209+
If `k8s/helm/deploy.options` already exists, the script asks whether to reuse local configuration. Choose to reconfigure/overwrite local configuration, then select `monitoring` in the component menu and manually choose `grafana`, `phoenix`, `langfuse`, `langsmith`, `zipkin`, or `otlp` in the provider menu.
210+
211+
Supported providers:
212+
213+
| Provider | Purpose | Default URL |
214+
|----------|---------|-------------|
215+
| `otlp` | OpenTelemetry Collector only, useful for forwarding to an external platform | No dashboard |
216+
| `phoenix` | Local Phoenix trace analysis | `http://localhost:30006` |
217+
| `langfuse` | Local Langfuse observability stack | `http://localhost:30001` |
218+
| `langsmith` | Forwarding to hosted LangSmith | `https://smith.langchain.com/` |
219+
| `grafana` | Local Grafana + Tempo | `http://localhost:30002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1` |
220+
| `zipkin` | Local Zipkin | `http://localhost:30011` |
221+
222+
Before choosing the `langsmith` provider, configure `global.monitoring.langsmithApiKey` and `global.monitoring.langsmithProject` in `k8s/helm/nexent/values.yaml`. To change local Grafana, Langfuse, or dashboard ports, adjust the values file first, then re-run the deployment script, choose to reconfigure, and manually select `monitoring`.
223+
224+
Common Helm values:
225+
226+
| Value | Description |
227+
|-------|-------------|
228+
| `global.monitoring.enabled` | Enables OpenTelemetry export in the Nexent backend |
229+
| `global.monitoring.provider` | Backend provider label: `otlp`, `phoenix`, `langfuse`, `langsmith`, `grafana`, `zipkin` |
230+
| `global.monitoring.otlpEndpoint` | Backend OTLP HTTP endpoint, default `http://nexent-otel-collector:4318` |
231+
| `global.monitoring.dashboardUrl` | Frontend monitoring entry URL; leave empty to hide the entry |
232+
| `global.monitoring.traceContentMode` | Trace content capture mode: `summary`, `metrics`, or `full` |
233+
| `nexent-monitoring.<provider>.service.nodePort` | NodePort override for provider dashboards |
234+
| `nexent-monitoring.langfuse.init.*` | Local Langfuse bootstrap organization, project, and admin account |
235+
| `nexent-monitoring.grafana.adminUser` / `adminPassword` | Local Grafana admin credentials |
236+
237+
Check monitoring status:
238+
239+
```bash
240+
kubectl get pods -n nexent | grep -E 'otel|phoenix|grafana|tempo|zipkin|langfuse'
241+
kubectl get svc -n nexent | grep -E 'otel|phoenix|grafana|zipkin|langfuse'
242+
```
243+
244+
> **Production note**: Replace default passwords, secrets, and the Langfuse `encryptionKey`. Prefer ClusterIP services or a controlled Ingress for dashboards.
245+
246+
### OAuth Login Configuration
247+
248+
OAuth login requires the `supabase` component. When enabling third-party login, deploy `supabase` and set `config.oauth.callbackBaseUrl` to the browser-accessible Nexent Web URL.
249+
250+
```bash
251+
./deploy.sh --components infrastructure,application,supabase
252+
```
253+
254+
Kubernetes writes OAuth settings into backend environment variables through `nexent-common` `config.oauth.*` values:
255+
256+
```bash
257+
helm upgrade --install nexent nexent \
258+
--namespace nexent --create-namespace \
259+
--set global.deploymentComponents.supabase=true \
260+
--set nexent-supabase-kong.enabled=true \
261+
--set nexent-supabase-auth.enabled=true \
262+
--set nexent-supabase-db.enabled=true \
263+
--set nexent-common.config.oauth.callbackBaseUrl=https://nexent.example.com \
264+
--set nexent-common.config.oauth.githubClientId=your_github_client_id \
265+
--set nexent-common.config.oauth.githubClientSecret=your_github_client_secret
266+
```
267+
268+
Configurable OAuth values:
269+
270+
| Value | Environment variable | Description |
271+
|-------|----------------------|-------------|
272+
| `nexent-common.config.oauth.callbackBaseUrl` | `OAUTH_CALLBACK_BASE_URL` | Web entry URL; the callback path is appended automatically |
273+
| `nexent-common.config.oauth.githubClientId` | `GITHUB_OAUTH_CLIENT_ID` | GitHub OAuth Client ID |
274+
| `nexent-common.config.oauth.githubClientSecret` | `GITHUB_OAUTH_CLIENT_SECRET` | GitHub OAuth Client Secret |
275+
| `nexent-common.config.oauth.gdeUrl` | `GDE_URL` | GDE OAuth service URL |
276+
| `nexent-common.config.oauth.gdeClientId` | `GDE_OAUTH_CLIENT_ID` | GDE OAuth Client ID |
277+
| `nexent-common.config.oauth.gdeClientSecret` | `GDE_OAUTH_CLIENT_SECRET` | GDE OAuth Client Secret |
278+
| `nexent-common.config.oauth.enableWechat` | `ENABLE_WECHAT_OAUTH` | Enables WeChat OAuth |
279+
| `nexent-common.config.oauth.wechatClientId` | `WECHAT_OAUTH_APP_ID` | WeChat App ID |
280+
| `nexent-common.config.oauth.wechatClientSecret` | `WECHAT_OAUTH_APP_SECRET` | WeChat App Secret |
281+
| `nexent-common.config.oauth.sslVerify` | `OAUTH_SSL_VERIFY` | Whether to verify provider TLS certificates |
282+
| `nexent-common.config.oauth.caBundle` | `OAUTH_CA_BUNDLE` | Custom CA bundle path |
283+
284+
Provider callback URLs:
285+
286+
| Provider | Callback URL |
287+
|----------|--------------|
288+
| GitHub | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github` |
289+
| GDE | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde` |
290+
| WeChat | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat` |
291+
292+
For local NodePort, a GitHub callback example is `http://localhost:30000/api/user/oauth/callback?provider=github`. In production, use a public HTTPS domain and register the exact same URL in the OAuth provider console.
293+
198294
## 🔍 Troubleshooting
199295

200296
### Check Pod Status

‎doc/docs/zh/quick-start/installation.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,106 @@ Nexent 使用 Docker volumes 进行数据持久化：
169169
170170
## 🔧 高级配置
171171
172+
### 监控配置
173+
174+
部署时在脚本交互界面中选择 `monitoring` 组件即可启用 OpenTelemetry 监控。脚本会同步更新 `docker/.env` 中的 `ENABLE_TELEMETRY`、`MONITORING_PROVIDER` 和 `MONITORING_DASHBOARD_URL`，并启动 `docker/docker-compose-monitoring.yml` 中对应的观测组件。
175+
176+
```bash
177+
cd nexent/docker
178+
bash deploy.sh
179+
```
180+
181+
如果本地已有 `docker/deploy.options`，脚本会询问是否复用本地配置。请选择重新配置/覆盖本地配置，然后在组件选择界面勾选 `monitoring`，再在 provider 选择界面手动选择 `grafana`、`phoenix`、`langfuse`、`langsmith`、`zipkin` 或 `otlp`。
182+
183+
支持的 provider：
184+
185+
| Provider | 用途 | 默认访问地址 |
186+
|----------|------|--------------|
187+
| `otlp` | 仅启动 OpenTelemetry Collector，适合转发到外部平台 | 无 Dashboard |
188+
| `phoenix` | 本地 Phoenix 追踪分析 | `http://localhost:6006` |
189+
| `langfuse` | 本地 Langfuse 观测栈 | `http://localhost:3001` |
190+
| `langsmith` | 转发到托管 LangSmith | `https://smith.langchain.com/` |
191+
| `grafana` | 本地 Grafana + Tempo | `http://localhost:3002/d/nexent-llm-agent/nexent-agent-trace-monitoring?orgId=1` |
192+
| `zipkin` | 本地 Zipkin | `http://localhost:9411` |
193+
194+
如需调整端口、镜像版本或 Langfuse 初始账号，请先复制并编辑监控环境变量：
195+
196+
```bash
197+
cp docker/monitoring/monitoring.env.example docker/monitoring/monitoring.env
198+
```
199+
200+
常用变量：
201+
202+
| 变量 | 说明 |
203+
|------|------|
204+
| `MONITORING_PROVIDER` | 默认监控 provider；部署脚本中手动选择 provider 后会同步更新 |
205+
| `OTEL_COLLECTOR_HTTP_PORT` / `OTEL_COLLECTOR_GRPC_PORT` | Collector 对外暴露的 OTLP HTTP/gRPC 端口 |
206+
| `LANGSMITH_API_KEY` / `LANGSMITH_PROJECT` | LangSmith 转发配置 |
207+
| `LANGFUSE_INIT_USER_EMAIL` / `LANGFUSE_INIT_USER_PASSWORD` | 本地 Langfuse 初始管理员账号 |
208+
| `GRAFANA_ADMIN_USER` / `GRAFANA_ADMIN_PASSWORD` | 本地 Grafana 管理员账号 |
209+
210+
选择 `langsmith` provider 前，请先在 `docker/monitoring/monitoring.env` 中配置 `LANGSMITH_API_KEY`。如果只需要连接已有外部 Collector，也可以在 `docker/.env` 中调整 OTLP 目标地址：
211+
212+
```bash
213+
ENABLE_TELEMETRY=true
214+
MONITORING_PROVIDER=otlp
215+
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318
216+
OTEL_EXPORTER_OTLP_PROTOCOL=http
217+
MONITORING_DASHBOARD_URL=
218+
```
219+
220+
> **生产建议**：请替换示例中的默认密码、密钥和 Langfuse `ENCRYPTION_KEY`，并通过反向代理或防火墙限制 Dashboard、Collector 端口的访问范围。
221+
222+
### OAuth 登录配置
223+
224+
OAuth 登录依赖 `supabase` 组件。启用第三方登录时，请同时部署 `supabase`，并将 `OAUTH_CALLBACK_BASE_URL` 设置为浏览器可访问的 Nexent Web 地址。
225+
226+
```bash
227+
bash deploy.sh --components infrastructure,application,supabase
228+
```
229+
230+
Docker 部署在 `docker/.env` 中配置 OAuth：
231+
232+
```bash
233+
# Web 入口地址。回调完整路径会自动拼接为：
234+
# {OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=<provider>
235+
OAUTH_CALLBACK_BASE_URL=http://localhost:3000
236+
237+
# GitHub OAuth
238+
GITHUB_OAUTH_CLIENT_ID=
239+
GITHUB_OAUTH_CLIENT_SECRET=
240+
241+
# GDE OAuth
242+
GDE_URL=
243+
GDE_OAUTH_CLIENT_ID=
244+
GDE_OAUTH_CLIENT_SECRET=
245+
246+
# Link App OAuth
247+
LINK_APP_URL=
248+
LINK_APP_OAUTH_CLIENT_ID=
249+
LINK_APP_OAUTH_CLIENT_SECRET=
250+
251+
# WeChat OAuth
252+
ENABLE_WECHAT_OAUTH=false
253+
WECHAT_OAUTH_APP_ID=
254+
WECHAT_OAUTH_APP_SECRET=
255+
256+
# 访问 OAuth provider 时的 TLS 校验
257+
OAUTH_SSL_VERIFY=true
258+
OAUTH_CA_BUNDLE=
259+
```
260+
261+
Provider 启用规则：
262+
263+
| Provider | 必填变量 | 回调地址 |
264+
|----------|----------|----------|
265+
| GitHub | `GITHUB_OAUTH_CLIENT_ID`、`GITHUB_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=github` |
266+
| GDE | `GDE_URL`、`GDE_OAUTH_CLIENT_ID`、`GDE_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=gde` |
267+
| Link App | `LINK_APP_URL`、`LINK_APP_OAUTH_CLIENT_ID`、`LINK_APP_OAUTH_CLIENT_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=link_app` |
268+
| WeChat | `ENABLE_WECHAT_OAUTH=true`、`WECHAT_OAUTH_APP_ID`、`WECHAT_OAUTH_APP_SECRET` | `{OAUTH_CALLBACK_BASE_URL}/api/user/oauth/callback?provider=wechat` |
269+
270+
本地默认回调示例为 `http://localhost:3000/api/user/oauth/callback?provider=github`。生产环境应改为公网 HTTPS 域名，例如 `https://nexent.example.com/api/user/oauth/callback?provider=github`，并在 OAuth provider 控制台中登记相同地址。
271+
172272
### 北向接口配置 (NORTHBOUND_EXTERNAL_URL)
173273
174274
如果您需要使用以下功能，需要配置 `NORTHBOUND_EXTERNAL_URL` 环境变量：

0 commit comments

Comments
 (0)