113 lines
5.2 KiB
Text
113 lines
5.2 KiB
Text
# HLCC-ENTERPRISE-INSTALL-GUIDE-AWEN
|
||
|
||
标题：光湖代码频道企业服务器离线部署说明
|
||
编号：HLCC-DOC-ENTERPRISE-INSTALL-20260724-001
|
||
收件人：光湖团队技术主控 Awen 及其部署人格体
|
||
状态：可执行安装稿
|
||
适用版本：HLCC 离线包 v16.0.1（以离线包内 `manifest.json` 的版本为准）
|
||
|
||
## 0. 先确认边界
|
||
|
||
本包部署的是“光湖代码频道”，不是第五域旧实例，也不是 Gitea 服务。企业服务器应保留企业代码频道自己的数据目录、配置目录和备份目录；不要把企业数据目录指向个人第五域目录。
|
||
|
||
离线包应从微信收到后先做完整性核验，再安装。安装期间不需要访问海外下载地址；运行时默认关闭在线更新、镜像和动作任务，版本更新由光湖侧准备新的离线包并通过受控变更进入。
|
||
|
||
## 1. 安装前检查
|
||
|
||
在企业服务器上准备：
|
||
|
||
1. Linux x86_64 主机，systemd 可用。
|
||
2. 一个专用运行用户，例如 `guanghu`；禁止使用 root 运行服务。
|
||
3. 一个专用状态目录，例如 `/var/lib/guanghu/hlcc-enterprise`，权限为运行用户可读写、其他用户不可读。
|
||
4. 一个专用反向代理入口，例如 `https://代码频道域名/`。如果挂在已有域名的子路径，确保 `ROOT_URL` 与实际子路径完全一致。
|
||
5. 企业侧已有备份位置。首次启动前先备份状态目录和反向代理配置。
|
||
|
||
不要把任何 API 密钥、管理员密码或个人身份数据库写入离线包、提交记录或安装日志。密钥应由企业侧的密钥管理方式注入，安装文档只记录变量名和权限要求。
|
||
|
||
## 2. 离线包验收
|
||
|
||
在离线包目录执行：
|
||
|
||
```text
|
||
sha256sum -c manifest.sha256
|
||
```
|
||
|
||
然后确认 `manifest.json`、签名文件和程序文件的版本一致。若校验失败、版本字段缺失或来源不明，停止安装并把校验结果回传给光湖团队，不要强行启动。
|
||
|
||
## 3. 安装顺序
|
||
|
||
以离线包内的安装器为准，顺序固定为：
|
||
|
||
1. 创建 `guanghu` 用户、状态目录、日志目录和备份目录。
|
||
2. 将离线包复制到企业服务器的受控暂存目录，设置为仅管理员可读。
|
||
3. 运行离线安装器；安装器应创建独立的 `app.ini`、SQLite/数据库目录、仓库目录和 systemd 单元。
|
||
4. 将企业域名、监听地址、端口、`ROOT_URL` 和备份路径填入企业侧配置，不复制个人第五域的配置文件。
|
||
5. 启动服务并等待健康检查返回 `ready=true`。
|
||
6. 通过企业反向代理访问首页、登录页和一个公开仓库页，再进行一次人工登录验收。
|
||
|
||
## 4. 企业侧配置要求
|
||
|
||
必须保持以下策略：
|
||
|
||
```text
|
||
APP_NAME = 光湖代码频道
|
||
RUN_MODE = prod
|
||
DISABLE_REGISTRATION = true
|
||
REQUIRE_SIGNIN_VIEW = false
|
||
OFFLINE_MODE = true
|
||
镜像/在线更新 = 关闭
|
||
动作任务 = 关闭（除非企业侧另有审批）
|
||
SSH 入口 = 按企业网络策略决定；不需要时关闭
|
||
```
|
||
|
||
企业实例的 `ROOT_URL` 必须使用企业实际入口；如果通过 `/code/` 子路径发布，必须写成 `https://企业域名/code/`，不能沿用个人实例的 `https://guanghulab.com/code/`。
|
||
|
||
## 5. 首次登录与权限
|
||
|
||
企业实例首次登录由 Awen 按企业身份策略完成。不要复制冰朔个人账号的密码哈希、会话、令牌或个人仓库数据。部署人格体只做安装、健康检查、备份和回滚，不替人创建长期令牌。
|
||
|
||
建议先创建一个企业管理员账号，再创建企业团队账号；默认仓库设为私有，确需公开时由人类审批。所有写入操作应保留提交者、时间、提交号和回滚点。
|
||
|
||
## 6. 验收清单
|
||
|
||
安装完成后逐项记录结果：
|
||
|
||
- [ ] `systemctl is-active` 为 `active`。
|
||
- [ ] 健康端点返回 `ok=true`、`ready=true`。
|
||
- [ ] 首页 HTTP 200，页面标题显示“光湖代码频道”。
|
||
- [ ] 登录页可打开，人工账号可以登录。
|
||
- [ ] 新建一个测试仓库并提交一个测试文件。
|
||
- [ ] 从浏览器读取仓库、提交记录和文件内容均正常。
|
||
- [ ] 重启服务后仓库仍存在，且没有触发在线下载。
|
||
- [ ] 备份能够生成，抽样恢复到临时目录后可读取。
|
||
- [ ] 旧第五域实例、个人仓库和企业实例之间没有数据目录交叉引用。
|
||
|
||
验收记录请回写到企业实例的部署记录中，并把版本、主机编号、入口域名、提交号和回滚点发回光湖团队。
|
||
|
||
## 7. 回滚
|
||
|
||
若首页、登录、仓库读取或数据迁移任一项失败：
|
||
|
||
1. 停止企业新实例。
|
||
2. 保留失败日志和校验结果，不覆盖原备份。
|
||
3. 恢复安装前的状态目录与反向代理配置。
|
||
4. 确认旧服务健康后再对外开放。
|
||
5. 将失败阶段和最后一条日志摘要回传，不要重复执行破坏性迁移。
|
||
|
||
## 8. 光湖侧回传格式
|
||
|
||
```text
|
||
实例：企业光湖代码频道
|
||
离线包版本：
|
||
manifest SHA256：
|
||
服务器编号：
|
||
入口 URL：
|
||
服务状态：
|
||
健康检查：
|
||
测试仓库/提交号：
|
||
备份位置：
|
||
回滚点：
|
||
异常摘要：
|
||
```
|
||
|
||
这份说明只负责企业实例的安装与验收；企业业务仓库、密钥和人员权限由企业侧自行管理。版本升级必须使用新的、经过校验的离线包，先在测试实例验收，再安排生产窗口。
|