exceptionless/api

Exceptionless Server Docker 镜像文档

概述

Exceptionless Server 是一个开源的实时错误跟踪与日志聚合解决方案，提供自托管部署选项。该平台旨在帮助开发者实时捕获、集中管理并分析应用程序运行时的异常、错误和日志数据，通过可视化界面和强大的分析工具，加速问题定位与解决，从而提升应用可靠性和用户体验。作为开源项目（https://github.com/exceptionless/Exceptionless%EF%BC%89%EF%BC%8C%E7%94%A8%E6%88%B7%E5%8F%AF%E5%AE%8C%E5%85%A8%E6%8E%A7%E5%88%B6%E6%95%B0%E6%8D%AE%E5%AD%98%E5%82%A8%E4%B8%8E%E9%9A%90%E7%A7%81%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E5%AF%B9%E6%95%B0%E6%8D%AE%E5%AE%89%E5%85%A8%E6%80%A7%E6%9C%89%E8%BE%83%E9%AB%98%E8%A6%81%E6%B1%82%E7%9A%84%E5%9C%BA%E6%99%AF%E3%80%82

核心功能与特性

实时错误捕获与跟踪

• 支持捕获多种类型的异常（如未处理异常、已处理异常、自定义异常）
• 实时上报错误数据，最小化延迟
• 自动收集错误上下文信息（堆栈跟踪、环境变量、请求详情等）

日志聚合与管理

• 集中收集应用程序日志（支持结构化与非结构化日志）
• 提供日志过滤、搜索与排序功能
• 支持按级别（Info/Warn/Error等）、来源、时间范围分类日志

用户会话与事件分析

• 跟踪用户会话数据，关联错误与用户行为路径
• 提供事件趋势图表，展示错误发生率、频率变化
• 支持自定义事件标记，满足业务监控需求

多平台与通知集成

• 兼容 Web、移动（iOS/Android）、桌面应用
• 支持通过邮件、Slack、Microsoft Teams 等渠道发送告警通知
• 提供 REST API 与 SDK（C#/JavaScript/Java 等），便于应用集成

自托管与数据安全

• 支持本地服务器或私有云部署，数据完全自主管理
• 可配置数据保留策略，控制存储占用
• 支持 HTTPS 加密传输，保障数据安全性

使用场景与适用范围

应用类型

• Web 应用：监控后端 API、前端 JavaScript 错误
• 移动应用：捕获 iOS/Android 应用崩溃与异常
• 桌面应用：跟踪 Windows/macOS 桌面程序运行时问题
• 微服务架构：集中管理多个服务节点的日志与错误

环境需求

• 开发环境：实时捕获调试阶段的异常，加速问题修复
• 测试环境：监控回归测试中的潜在问题
• 生产环境：持续跟踪线上应用稳定性，及时响应故障

使用方法与配置说明

前提条件

• 已安装 Docker Engine（20.10+）与 Docker Compose（v2+）
• 服务器建议配置：2核 CPU、4GB RAM、20GB 可用磁盘空间（视日志量调整）

快速启动（单容器模式）

以下命令启动 Exceptionless Server 单容器实例（依赖内置 SQLite，适合测试环境）：

bash
docker run -d -p 5000:80 --name exceptionless \
  -e EX_AppMode=Development \
  -e EX_ConnectionStrings__Default=Data Source=/app/data/exceptionless.db \
  -v exceptionless-data:/app/data \
  exceptionless/exceptionless:latest

• -p 5000:80：映射容器 80 端口到主机 5000 端口
• -v exceptionless-data:/app/data：持久化存储数据（日志、配置等）
• EX_AppMode：设置运行模式（Development/Production）
• EX_ConnectionStrings__Default：数据库连接字符串（内置 SQLite）

生产环境部署（Docker Compose）

生产环境建议使用 Redis（缓存）+ Elasticsearch（日志存储）架构，通过 Docker Compose 部署：

1. 创建 docker-compose.yml 文件：

yaml
version: '3.8'

services:
  exceptionless:
    image: exceptionless/exceptionless:latest
    ports:
      - "5000:80"
    environment:
      - EX_AppMode=Production
      - EX_ConnectionStrings__Redis=redis://redis:6379
      - EX_ConnectionStrings__Elasticsearch=http://elasticsearch:9200
      - EX_ConnectionStrings__Default=Server=sql;Database=exceptionless;User Id=sa;Password=YourStrong!Passw0rd;
      - EX_Smtp__Host=smtp.example.com
      - EX_Smtp__Port=587
      - EX_Smtp__UseSsl=true
      - EX_Smtp__UserName=alerts@example.com
      - EX_Smtp__Password=your-smtp-password
    depends_on:
      - redis
      - elasticsearch
      - sql
    volumes:
      - exceptionless-config:/app/config
      - exceptionless-assets:/app/wwwroot/assets

  redis:
    image: redis:7-alpine
    volumes:
      - redis-data:/data

  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:8.10.4
    environment:
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - elasticsearch-data:/usr/share/elasticsearch/data

  sql:
    image: mcr.microsoft.com/mssql/server:2022-latest
    environment:
      - ACCEPT_EULA=Y
      - SA_PASSWORD=YourStrong!Passw0rd
    volumes:
      - sql-data:/var/opt/mssql

volumes:
  exceptionless-config:
  exceptionless-assets:
  redis-data:
  elasticsearch-data:
  sql-data:

2. 启动服务栈：

bash
docker-compose up -d

持久化数据配置

通过 Docker 卷（Volumes）持久化关键数据，避免容器重启后数据丢失：

• exceptionless-config：存储应用配置文件
• exceptionless-assets：存储静态资源（如上传的日志文件）
• redis-data：Redis 缓存数据
• elasticsearch-data：Elasticsearch 索引数据（日志与事件）
• sql-data：SQL Server 数据库数据（用户信息、权限等）

应用集成示例

部署完成后，需在应用中集成 Exceptionless SDK 以发送事件/错误数据。以下为常见语言示例：

C# 应用集成

csharp
// 安装 NuGet 包：Install-Package Exceptionless
using Exceptionless;

ExceptionlessClient.Default.Configuration.ApiKey = "YOUR_API_KEY";
ExceptionlessClient.Default.Configuration.ServerUrl = "http://your-exceptionless-server:5000";

try {
  // 业务逻辑代码
} catch (Exception ex) {
  ex.ToExceptionless().Submit(); // 提交异常
}

// 发送自定义日志
ExceptionlessClient.Default.SubmitLog("User login failed", "warn", new { UserId = "123", IP = "192.168.1.1" });

JavaScript 应用集成

javascript
// 引入 SDK：npm install exceptionless
import { ExceptionlessClient } from 'exceptionless';

const client = new ExceptionlessClient({
  apiKey: 'YOUR_API_KEY',
  serverUrl: 'http://your-exceptionless-server:5000'
});

try {
  // 业务逻辑代码
} catch (ex) {
  client.submitException(ex); // 提交异常
}

// 发送自定义事件
client.submitEvent({
  type: 'UserView',
  data: { Page: 'Home', UserAgent: navigator.userAgent }
});

访问与管理

1. 服务启动后，通过 http://<服务器IP>:5000 访问 Web 管理界面
2. 首次登录需创建管理员账户（默认无初始用户）
3. 在 项目设置 中创建应用项目，获取 API Key
4. 配置通知规则（如错误阈值告警、邮件通知频率等）

环境变量配置

常用环境变量说明（完整列表见 https://github.com/exceptionless/Exceptionless%EF%BC%89%EF%BC%9A

注意事项

• 生产环境建议使用外部 Redis 与 Elasticsearch 集群，提升性能与可靠性
• 定期备份持久化卷数据，避免数据丢失
• 高并发场景下可水平扩展 Exceptionless Server 实例（需配置共享 Redis 与 Elasticsearch）
• 遵循官方安全最佳实践，如配置 HTTPS（通过反向代理如 Nginx）、限制 API 访问频率等